{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/beel-es/json-schema/beel-es-update-company-payment-connection-request-schema.json",
  "title": "UpdateCompanyPaymentConnectionRequest",
  "description": "The settings to change. A field you omit keeps its current value; the series fields and\n`tax_inclusive_tax` also accept an explicit `null`, which clears them.\n",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/beel-es-companypaymentconnections-api-openapi.yml#/components/schemas/UpdateCompanyPaymentConnectionRequest",
  "type": "object",
  "properties": {
    "auto_invoice_enabled": {
      "type": "boolean",
      "description": "Whether incoming charges are auto-invoiced."
    },
    "event_source": {
      "allOf": [
        {
          "$ref": "#/$defs/PaymentConnectionEventSource"
        }
      ],
      "description": "Which family of Stripe events this connection acts on. Changing it affects the events\nthat arrive from then on; events already recorded keep their outcome.\n"
    },
    "auto_create_customer": {
      "type": "boolean",
      "description": "Whether customers are created from the fiscal data the provider supplies."
    },
    "send_invoice_by_email": {
      "type": "boolean",
      "description": "Whether the auto-issued invoice is emailed to the payer."
    },
    "tax_inclusive_tax": {
      "allOf": [
        {
          "$ref": "#/$defs/TaxInfo"
        }
      ],
      "description": "Optional. The tax applied to a charge for which the provider sends no tax breakdown;\nwhen set, it takes precedence over the company's tax configuration for those charges.\nOmit it to keep the current value; send `null` to clear it, so the company's tax\nconfiguration applies again.\n"
    },
    "series": {
      "$ref": "#/$defs/UpdateCompanyPaymentConnectionSeries"
    },
    "simplificada_threshold": {
      "type": "number",
      "format": "double",
      "minimum": 0.01,
      "maximum": 3000,
      "description": "Amount in EUR up to which a charge whose buyer has no complete fiscal data (tax ID, name\nand address) is invoiced as a simplified invoice. Above it, the charge is not issued: it\nwaits as a draft standard invoice until the buyer's fiscal data is completed. A buyer with\ncomplete fiscal data always gets a standard invoice, whatever the amount. Up to 400.00 is\nthe general limit; a higher value, up to 3000.00, is the issuer's statement that its\nactivity is one of those in article 4.2 of RD 1619/2012 (rule SIM-002). Omit to keep\nthe current value.\n"
    },
    "filter_config": {
      "allOf": [
        {
          "$ref": "#/$defs/CompanyPaymentConnectionFilters"
        }
      ],
      "description": "Omit to keep the current filter configuration untouched. When sent, it **replaces the\nwhole object** — every axis you leave out is cleared, not preserved. Send the complete\nconfiguration you want, not just the axis you are changing.\n"
    }
  },
  "$defs": {
    "CompanyPaymentConnectionFilters": {
      "type": "object",
      "description": "Rules that decide which incoming charges reach auto-invoicing. Every axis is opt-in: a\nfield left out does not filter anything. A charge filtered out produces no invoice and is\nrecorded as skipped.\n",
      "properties": {
        "min_amount": {
          "type": "number",
          "format": "double",
          "minimum": 0,
          "description": "Charges below this amount are skipped."
        },
        "max_amount": {
          "type": "number",
          "format": "double",
          "minimum": 0,
          "description": "Charges above this amount are skipped."
        },
        "only_mapped_customers": {
          "type": "boolean",
          "description": "When true, only charges from customers already mapped to a BeeL customer are invoiced.\n"
        },
        "allowed_customer_ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Provider-side customer ids (e.g. Stripe `cus_...`) allowed through. When set, no other\ncustomer is invoiced.\n"
        },
        "excluded_description_patterns": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Regular expressions matched against the charge description. A charge matching any of\nthem is skipped.\n"
        },
        "required_description_patterns": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Regular expressions matched against the charge description. A charge must match at\nleast one of them to be invoiced.\n"
        },
        "disabled_categories": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/PaymentEventCategory"
          },
          "description": "Charge categories opted out of auto-invoicing. An empty list, or the field left out,\nleaves every category active.\n"
        }
      }
    },
    "PaymentConnectionEventSource": {
      "type": "string",
      "enum": [
        "PAYMENTS",
        "INVOICES",
        "BOTH"
      ],
      "description": "Which family of Stripe events the connection invoices. One webhook endpoint receives\neverything the connected account emits; whatever falls outside the declared family is\nrecorded as skipped, deliberately ignored, and needs no attention.\n\n- `PAYMENTS`: charges, through `payment_intent.*` and `checkout.session.*`.\n- `INVOICES`: Stripe's own billing documents, through `invoice.*`.\n- `BOTH`: both families, deduplicated to a single invoice per charge.\n\nRefunds, disputes and credit notes are acted on under every value, because Stripe does not\nalways report a correction through the family the charge came in. A correction whose charge\nwas never invoiced is recorded as skipped and needs no action.\n"
    },
    "PaymentEventCategory": {
      "type": "string",
      "description": "Which product line a payment event's money came from. A different axis from `event_kind`,\nwhich says what happened: a `checkout.session.completed` is `PAYMENT_COMPLETED` either way,\nand the category tells you whether it was a one-off checkout or the start of a subscription.\n\n- `DIRECT_PAYMENT`: a one-off charge\n- `SUBSCRIPTION`: a charge produced by a recurring subscription\n- `REFUND`: money given back\n- `CREDIT_NOTE`: a credit note issued on the provider's side\n",
      "enum": [
        "DIRECT_PAYMENT",
        "SUBSCRIPTION",
        "REFUND",
        "CREDIT_NOTE"
      ]
    },
    "RegimeKey": {
      "type": "string",
      "enum": [
        "01",
        "02",
        "03",
        "04",
        "05",
        "06",
        "07",
        "08",
        "09",
        "10",
        "11",
        "14",
        "15",
        "17",
        "18",
        "19",
        "20"
      ],
      "description": "Regime key according to VeriFactu regulations. Omitted, `01` (general regime) applies:\n- 01: General regime operation\n- 02: Export (IVA and IGIC; not IPSI, whose AEAT list is `01, 08, 11, 18, 19, 20`)\n- 03: Used goods, art, antiques (not accepted, see below)\n- 04: Investment gold\n- 05: Travel agencies\n- 06: Group of entities (not accepted, see below)\n- 07: Cash basis\n- 08: Operation subject to another indirect tax — IPSI or IGIC on an IVA line, IPSI or IVA\n  on an IGIC line. It is **not** the general regime of IGIC, which is `01`.\n- 09: Mediating agencies\n- 10: Third-party collections\n- 11: Local rental\n- 14: VAT pending in certifications (not accepted, see below)\n- 15: VAT pending successive tract\n- 17: OSS and IOSS\n- 18: Equivalence surcharge\n- 19: REAGYP\n- 20: Simplified regime\n\n**What AEAT requires with each key** (Validaciones VERI*FACTU 3.1.3.15.6), checked on\nIVA and IGIC lines before the invoice is numbered. Otherwise the request is rejected with\n`422` and the code in brackets:\n- `04`: only reverse charge (an `ISP_ART_84_2_*` reason) or an exemption\n  (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`).\n- `08`: only `exemption_reason: NO_SUJETA_LOCALIZACION`, at 0 %\n  (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`).\n- `10`: only `exemption_reason: NO_SUJETA_ART_7_9`, on a `STANDARD` invoice whose\n  recipient has a `nif` (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`,\n  `REGIME_KEY_REQUIRES_STANDARD_INVOICE`, `REGIME_KEY_REQUIRES_RECIPIENT_NIF`).\n- `11` (IVA): a subject line only at 21 %, and no reverse charge\n  (`REGIME_KEY_REQUIRES_VAT_RATE`, `REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`).\n- `06` and `14` are not accepted (`REGIME_KEY_NOT_SUPPORTED`): AEAT requires with them\n  data the invoice does not carry (a cost-based taxable base; an operation date after the\n  issue date and a public-administration recipient).\n- `03` (used goods) is not accepted (`REGIME_KEY_NOT_SUPPORTED`): under it the invoice\n  must not show the tax separately (RD 1619/2012, art. 16.2.c), and it always does. The\n  corrective of an invoice that already carried `03` keeps it.\n- `05` (travel agencies) and `07` (cash basis) are accepted, and the invoice PDF carries\n  the mention of their regime (RD 1619/2012, art. 6.1 n and p). `07`: no reverse charge,\n  no non-subject reason and, of the exemptions, only art. 20 or `OTRO`\n  (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`).\n`GET /v1/tax-types` only offers the keys that are accepted.\n\n**One exception to \"a key you send is the key you get\":** when the line ends up\ncarrying an equivalence surcharge — whether you sent `equivalence_surcharge_rate`\nor it was inherited from the company's tax configuration — a `01` is rewritten to\n`18`, because a surcharge under the general regime is fiscally incoherent. Send\n`equivalence_surcharge_rate: 0` explicitly to keep `01`. See\n`equivalence_surcharge_rate` in the invoice line for the full rules.\n"
    },
    "TaxInfo": {
      "type": "object",
      "required": [
        "type",
        "percentage"
      ],
      "properties": {
        "type": {
          "$ref": "#/$defs/TaxType"
        },
        "percentage": {
          "type": "number",
          "minimum": 0,
          "maximum": 100,
          "description": "Tax percentage"
        },
        "regime_key": {
          "$ref": "#/$defs/RegimeKey"
        }
      },
      "description": "Complete tax information with cross-validations:\n- IVA: real rates 4, 10, 21, and the temporary 2, 5 and 7.5 (see below for 0)\n- IGIC: 0, 3, 5, 7, 9.5, 15, 20 — here 0 is the real \"Tipo Cero\"\n- IPSI: real rates 0.5, 1, 2, 4, 8, 10 (see below for 0)\n- OTHER: any percentage between 0 and 100\n\n**0 % under IVA and IPSI is not a rate, it is the exemption sentinel.** It is accepted\non a line, but only together with an `exemption_reason` (exempt or non-subject\noperation); on its own it says nothing and the line is rejected. That is why\n`GET /v1/tax-types` publishes the IVA rates without 0: the legitimate way\nto a 0 % IVA line is through an exemption reason, which the same response also\npublishes. IGIC is different — its 0 % is a real legal rate (basic necessities) and\nneeds no reason.\n\n**IVA 5 %** (the temporary rate applied from 2022 to electricity, gas and certain\nfoodstuffs) is no longer in force for new operations. AEAT only accepts it on operations\ndated from 2022-07-01 to 2024-09-30: send the `operation_date` of that period, because\nwithout one the issue date decides and a line at 5 % is rejected with\n`422 VAT_RATE_NOT_ACCEPTED_ON_DATE`. Its equivalence surcharge pair is 0.5 up to 2022-12-31\nand 0.62 from 2023-01-01. **IVA 2 % and 7.5 %** (temporary rates of the last quarter of 2024)\nare accepted only on operations dated from 2024-10-01 to 2024-12-31, with surcharges 0.26\nand 1.\n\nException: when regime_key = \"17\" (OSS/IOSS) the invoice applies the destination\ncountry VAT instead of the Spanish one, so any percentage in the EU range [0, 27]\nis accepted regardless of the tax type set — including 0 without an exemption reason.\n"
    },
    "TaxType": {
      "type": "string",
      "enum": [
        "IVA",
        "IGIC",
        "IPSI",
        "OTHER"
      ],
      "description": "Tax type by territory:\n- IVA: Iberian Peninsula and Balearic Islands (4%, 10%, 21%; 2%, 5% and 7.5% only on operations of their period)\n- IGIC: Canary Islands (0%, 3%, 5%, 7%, 9.5%, 15%, 20%)\n- IPSI: Ceuta and Melilla (0.5%, 1%, 2%, 4%, 8%, 10%)\n- OTHER: Configurable 0%-100%\n\nUnder IVA and IPSI, 0% is not one of these rates: it is the exemption/non-subject\nsentinel and always travels with an `exemption_reason`. IGIC's 0% is a real rate.\nSee `TaxInfo` for the full rules.\n"
    },
    "UpdateCompanyPaymentConnectionSeries": {
      "type": "object",
      "description": "Series to number auto-issued invoices in. Omit a field to keep it, send `null` to clear it\nand fall back to the company default series for that document type.\n",
      "properties": {
        "ordinaria": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid",
          "description": "Series for auto-issued ordinary invoices."
        },
        "simplificada": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid",
          "description": "Series for auto-issued simplified invoices."
        },
        "rectificativa": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid",
          "description": "Series for auto-issued corrective invoices (refunds)."
        }
      }
    }
  }
}