{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/beel-es/json-schema/beel-es-customer-bulk-delete-result-schema.json",
  "title": "CustomerBulkDeleteResult",
  "description": "Report of a bulk delete of customers, in the same shape every batch operation of this API\nuses (ADR-0011): `metadata` (what the operation was), **one entry per identifier submitted**\nin its original position and never filtered, and `statistics` derived by counting those\nentries.\n\n**This endpoint deletes, it does not deactivate.** A deleted customer is retained internally\nfor tax record-keeping but is no longer exposed by the API, and **its identifier is released\nfor reuse** (the unique indexes only cover rows that are not deleted). Deactivating is the\nopposite: the customer stays where it is, marked inactive, with its NIF still taken. A\ncustomer that has invoices can never be deleted — it can only be deactivated — which is why\nit gets its own row status (`HAS_INVOICES`) instead of being reported as a failure.\n\n**HTTP status:** always `200` when the request was processed, even if no row could be\ndeleted. The code says whether the request was processed, not whether every row went well;\nthe split is in this report.\n",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/beel-es-companycustomers-api-openapi.yml#/components/schemas/CustomerBulkDeleteResult",
  "type": "object",
  "required": [
    "metadata",
    "customers_deletion",
    "statistics",
    "deleted_ids",
    "total",
    "successful",
    "failed",
    "deactivated_ids"
  ],
  "properties": {
    "metadata": {
      "$ref": "#/$defs/CustomerBulkDeleteMetadata"
    },
    "customers_deletion": {
      "type": "array",
      "description": "One entry per identifier submitted, in the order they were sent and never filtered: a\ncustomer that was not deleted keeps its place and its `index`, so the response lines up\nwith the request.\n",
      "items": {
        "$ref": "#/$defs/CustomerBulkDeleteItem"
      }
    },
    "statistics": {
      "$ref": "#/$defs/CustomerBulkDeleteStatistics"
    },
    "deleted_ids": {
      "type": "array",
      "description": "IDs of the customers that were deleted.",
      "items": {
        "$ref": "#/$defs/UUID"
      }
    },
    "deactivated_ids": {
      "type": "array",
      "deprecated": true,
      "description": "**Deprecated alias of `deleted_ids`** — identical content. The name was wrong: this\noperation deletes (freeing the identifier), it does not deactivate (which keeps it\ntaken). Read `deleted_ids`. It will be removed no earlier than the `Sunset` date\nannounced for the deprecated flat routes.\n",
      "items": {
        "$ref": "#/$defs/UUID"
      }
    },
    "total": {
      "type": "integer",
      "deprecated": true,
      "description": "**Deprecated.** Same as `statistics.total_processed`."
    },
    "successful": {
      "type": "integer",
      "deprecated": true,
      "description": "**Deprecated.** Same as `statistics.deleted`."
    },
    "failed": {
      "type": "integer",
      "deprecated": true,
      "description": "**Deprecated.** Number of submitted identifiers that were NOT deleted, for whatever\nreason. It lumps together a customer that does not exist and one that has invoices and\nnever can be deleted — which is exactly why the per-row `status` exists. Read\n`statistics`.\n"
    },
    "errors": {
      "type": "array",
      "deprecated": true,
      "description": "**Deprecated.** Projection of the entries of `customers_deletion` that were not deleted,\nin the same order. Read `customers_deletion`, which also reports the rows that worked.\n",
      "items": {
        "$ref": "#/$defs/CustomerBulkDeleteLegacyError"
      }
    }
  },
  "$defs": {
    "CustomerBulkDeleteError": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "description": "Why a row was not deleted.",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable, uppercase, never translated — this is what an integration compares.\n`NOT_FOUND` means the id does not resolve to a customer of the company, and\n`INTERNAL_ERROR` that the row failed for an unexpected reason and was not deleted.\n`CLIENT_HAS_INVOICES` is deliberately the same code the single `DELETE` answers with\n`409`, so the single and the bulk route never disagree about the same customer.\n`CLIENT_HAS_RECURRING_INVOICE`: an active or paused recurring invoice uses the\ncustomer as its recipient. The single `DELETE` rejects the same case with `400`\n`REFERENCED_BY_RECURRING_INVOICE`.\n",
          "enum": [
            "NOT_FOUND",
            "CLIENT_HAS_INVOICES",
            "CLIENT_HAS_RECURRING_INVOICE",
            "INTERNAL_ERROR"
          ]
        },
        "message": {
          "type": "string",
          "description": "Human-readable text, already resolved to the language of the request."
        }
      }
    },
    "CustomerBulkDeleteItem": {
      "type": "object",
      "required": [
        "index",
        "customer_id",
        "status"
      ],
      "description": "How one submitted identifier ended up.",
      "properties": {
        "index": {
          "type": "integer",
          "description": "Position of the identifier in the submitted list (0-based)."
        },
        "customer_id": {
          "allOf": [
            {
              "$ref": "#/$defs/UUID"
            }
          ],
          "description": "The identifier that was submitted."
        },
        "status": {
          "type": "string",
          "enum": [
            "DELETED",
            "NOT_FOUND",
            "HAS_INVOICES",
            "HAS_RECURRING_INVOICE",
            "ERROR"
          ],
          "description": "Outcome of this row, in the vocabulary of deleting (deleting validates nothing\nbeforehand, so it does not speak of `VALID`):\n- `DELETED`: deleted; its identifier is free to be used again\n- `NOT_FOUND`: no such customer, or the current company/grant cannot see it\n- `HAS_INVOICES`: it has invoices, so it cannot be deleted — **deactivate it instead**\n  (`PATCH` with `active: false`). This is a business rule, not a failure: retrying the\n  delete will never work\n- `HAS_RECURRING_INVOICE`: an active or paused recurring invoice template uses it as its\n  customer, so it cannot be deleted — finish the template or change its customer first.\n  This is a business rule, not a failure: retrying the delete will never work\n- `ERROR`: an unexpected failure while processing this row\n"
        },
        "error": {
          "allOf": [
            {
              "$ref": "#/$defs/CustomerBulkDeleteError"
            }
          ],
          "description": "Present only when the customer was not deleted."
        }
      }
    },
    "CustomerBulkDeleteLegacyError": {
      "type": "object",
      "deprecated": true,
      "required": [
        "customer_id",
        "error"
      ],
      "description": "**Deprecated.** Legacy shape of a row that was not deleted.",
      "properties": {
        "customer_id": {
          "$ref": "#/$defs/UUID"
        },
        "error": {
          "$ref": "#/$defs/CustomerBulkDeleteError"
        }
      }
    },
    "CustomerBulkDeleteMetadata": {
      "type": "object",
      "required": [
        "total_customers",
        "operation",
        "is_dry_run"
      ],
      "description": "What the operation was, and whether it was a rehearsal.",
      "properties": {
        "total_customers": {
          "type": "integer",
          "description": "Number of identifiers submitted."
        },
        "operation": {
          "type": "string",
          "enum": [
            "DELETE_CUSTOMERS"
          ],
          "description": "The batch operation this report belongs to."
        },
        "is_dry_run": {
          "type": "boolean",
          "description": "Always `false`. Deleting has no rehearsal mode; the field is here so every batch report\nof this API has the same shape.\n"
        }
      }
    },
    "CustomerBulkDeleteStatistics": {
      "type": "object",
      "required": [
        "total_processed",
        "deleted",
        "not_found",
        "has_invoices",
        "has_recurring_invoice",
        "errors"
      ],
      "description": "Counters derived by counting the entries of `customers_deletion`, never accumulated while\nprocessing. Each row falls into exactly one of `deleted`, `not_found`, `has_invoices`,\n`has_recurring_invoice` and `errors`, so those five add up to `total_processed`.\n",
      "properties": {
        "total_processed": {
          "type": "integer",
          "description": "Identifiers submitted."
        },
        "deleted": {
          "type": "integer",
          "description": "Customers deleted (their identifiers are free again)."
        },
        "not_found": {
          "type": "integer",
          "description": "Identifiers that do not exist, or that the current company/grant cannot see."
        },
        "has_invoices": {
          "type": "integer",
          "description": "Customers that have invoices and therefore cannot be deleted. Not a failure: deactivate\nthem instead.\n"
        },
        "has_recurring_invoice": {
          "type": "integer",
          "description": "Customers with an active or paused recurring invoice template using them as its customer,\nand therefore cannot be deleted. Not a failure: finish the template or change its\ncustomer instead.\n"
        },
        "errors": {
          "type": "integer",
          "description": "Rows that failed for an unexpected reason."
        }
      }
    },
    "UUID": {
      "type": "string",
      "format": "uuid",
      "description": "Universally Unique Identifier (UUID v4)"
    }
  }
}