International customers

Every cross-border scenario — intra-EU B2B, B2C with OSS, exports, services to non-EU — with the exact request shape BeeL. accepts.

International invoices need the right combination of exemption_reason, main_tax.regime_key, and alternative_id. The wrong combination is almost always rejected by AEAT — and the right one is rarely obvious. This page walks every common scenario.

Identifying foreign customers

You can't use recipient.nif for non-Spanish customers — that field is reserved for Spanish NIFs. Use alternative_id instead:

{
  "recipient": {
    "legal_name": "Tech Europe GmbH",
    "alternative_id": {
      "type": "NIF_IVA",
      "number": "DE123456789",
      "country_code": "DE"
    }
  }
}

`alternative_id.type`	Code	Meaning	Allowed countries
`NIF_IVA`	`02`	EU VAT number (intra-community, VIES)	EU Member States other than ES
`PASSPORT`	`03`	Passport	Any country (including ES)
`COUNTRY_ID`	`04`	National ID in country of residence	Non-ES only
`RESIDENCE_CERTIFICATE`	`05`	Residence certificate	Non-ES only
`OTHER_DOCUMENT`	`06`	Any other identifier	Non-ES only
`NOT_REGISTERED`	`07`	Customer not registered in AEAT census	ES only

The country these rules refer to is alternative_id.country_code, not the country of the address. It is required, except for PASSPORT and NOT_REGISTERED, which take ES when you omit it; any other type without it answers 422 ALTERNATIVE_ID_COUNTRY_REQUIRED, with error.details naming alternative_id.country_code. Breaking the rules answers 422 ALTERNATIVE_ID_SPAIN_INVALID_TYPE (a type other than PASSPORT or NOT_REGISTERED with ES) or 422 ALTERNATIVE_ID_REQUIRES_SPAIN (NOT_REGISTERED with any other country).

A NIF_IVA is accepted only with the country of another EU Member State and in that State's EU VAT number format: the country prefix (EL for Greece) followed by the national number, without spaces — DE123456789, FR40303265045, EL094014201. Lowercase letters are accepted and stored in uppercase. A country outside the EU answers 422 ALTERNATIVE_ID_VAT_REQUIRES_EU_COUNTRY; a number without that structure, 422 ALTERNATIVE_ID_VAT_INVALID_FORMAT. Both are checked when you save the customer or send the invoice, and again when you issue, before a number is used. See CNT-021 A recipient without a Spanish NIF is identified by an alternative id.

The numeric codes ("02", "03", …, "07") are also accepted for backward compatibility but are deprecated. Prefer the descriptive names.

Well-formed is not the same as registered. BeeL. checks the structure of a NIF_IVA, not whether it is active in VIES. A number that has the right format but is not in the VIES census is refused by VeriFactu after the invoice is issued, and the invoice ends up REJECTED. Check the number in VIES before you invoice; if it is not there, identify the customer with COUNTRY_ID or OTHER_DOCUMENT and treat the operation as B2C.

Give a foreign address its country_code. address.country_code (ISO 3166-1 alpha-2) is the field that decides the country of the address — not alternative_id.country_code. country is accepted too, but only as a real ISO code ("BE") or the official name of the country in Spanish, English or Catalan ("Bélgica", "Belgium"); anything else, such as "UK", is rejected with 422 COUNTRY_CODE_REQUIRED (the code is GB), and a country that names a different country than country_code with 422 COUNTRY_CODE_MISMATCH. With neither field the address is Spanish: a Belgian postal code such as 1000 is then rejected with 422 POSTAL_CODE_INVALID_ES. Whatever you send, the response returns the code and the Spanish name derived from it ("country": "Bélgica", "country_code": "BE").

B2B intra-EU — goods (E5)

EU-to-EU sales of goods between two businesses with valid VIES VAT-IDs are exempt under Art. 25 LIVA. The buyer self-assesses IVA in their country.

curl -X POST "https://app.beel.es/api/v1/companies/{company_id}/invoices" \
  -H "Authorization: Bearer $BEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "STANDARD",
    "recipient": {
      "legal_name": "Acme NV",
      "alternative_id": { "type": "NIF_IVA", "number": "BE0404621642", "country_code": "BE" },
      "address": { "street": "Hauptstraße", "number": "456", "postal_code": "1000", "city": "Brussels", "province": "Brussels", "country": "Bélgica", "country_code": "BE" }
    },
    "lines": [
      {
        "description": "Hardware supply",
        "quantity": 1,
        "unit": "unit",
        "unit_price": 200,
        "discount_percentage": 0,
        "main_tax": { "type": "IVA", "percentage": 0, "regime_key": "01" },
        "exemption_reason": "EXENTA_ART_25"
      }
    ]
  }'

B2B intra-EU — services (N2)

Services to an EU business follow the general localisation rule (Art. 69 LIVA): they're deemed supplied where the customer is, so the operation is not subject to Spanish IVA. Use NO_SUJETA_LOCALIZACION (N2), not EXENTA_ART_25.

curl -X POST "https://app.beel.es/api/v1/companies/{company_id}/invoices" \
  -H "Authorization: Bearer $BEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "STANDARD",
    "recipient": {
      "legal_name": "Acme NV",
      "alternative_id": { "type": "NIF_IVA", "number": "BE0404621642", "country_code": "BE" },
      "address": { "street": "Hauptstraße", "number": "456", "postal_code": "1000", "city": "Brussels", "province": "Brussels", "country": "Bélgica", "country_code": "BE" }
    },
    "lines": [
      {
        "description": "B2B consulting service",
        "quantity": 1,
        "unit": "service",
        "unit_price": 200,
        "discount_percentage": 0,
        "main_tax": { "type": "IVA", "percentage": 0, "regime_key": "01" },
        "exemption_reason": "NO_SUJETA_LOCALIZACION"
      }
    ]
  }'

B2C intra-EU — below the OSS threshold

When you sell goods or services to an EU consumer and your total annual cross-border B2C sales are under 10,000 €, the operation tributes in origin. The invoice carries Spanish IVA just like a domestic B2C sale.

Identify the consumer with PASSPORT, COUNTRY_ID, or OTHER_DOCUMENT. Omit exemption_reason (default S1).

curl -X POST "https://app.beel.es/api/v1/companies/{company_id}/invoices" \
  -H "Authorization: Bearer $BEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "STANDARD",
    "recipient": {
      "legal_name": "Hans Müller",
      "alternative_id": { "type": "PASSPORT", "number": "F8624KW3J6", "country_code": "DE" },
      "address": { "street": "Müllerstraße", "number": "47", "postal_code": "80469", "city": "München", "province": "Bayern", "country": "Alemania", "country_code": "DE" }
    },
    "lines": [
      {
        "description": "Digital subscription",
        "quantity": 1,
        "unit": "month",
        "unit_price": 200,
        "discount_percentage": 0,
        "main_tax": { "type": "IVA", "percentage": 21, "regime_key": "01" }
      }
    ]
  }'

B2C intra-EU — above the OSS threshold

Above 10,000 €/year aggregated cross-border B2C sales (previous or current year), the destination country's IVA applies; the OSS (One-Stop Shop) regime is the optional way to declare it from Spain instead of registering in each country. From AEAT's perspective the operation is not subject to Spanish IVA, and main_tax.regime_key: "17" alone is what classifies it as N2. Keep the destination rate on the line (19 % for Germany below) and set no exemption_reason — adding one forces the rate to 0 % and drops the destination IVA from the breakdown.

curl -X POST "https://app.beel.es/api/v1/companies/{company_id}/invoices" \
  -H "Authorization: Bearer $BEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "STANDARD",
    "recipient": {
      "legal_name": "Hans Müller",
      "alternative_id": { "type": "PASSPORT", "number": "F8624KW3J6", "country_code": "DE" },
      "address": { "street": "Müllerstraße", "number": "47", "postal_code": "80469", "city": "München", "province": "Bayern", "country": "Alemania", "country_code": "DE" }
    },
    "lines": [
      {
        "description": "Digital subscription — OSS",
        "quantity": 1,
        "unit": "month",
        "unit_price": 200,
        "discount_percentage": 0,
        "main_tax": { "type": "IVA", "percentage": 19, "regime_key": "17" }
      }
    ]
  }'

Whether sales are above the 10,000 € threshold, and whether to declare them through OSS, are the issuer's to decide. Once you've registered for OSS, set regime_key: "17" on every cross-border B2C line.

Exports of goods (non-EU)

Goods leaving the EU customs territory are exempt under Art. 21 LIVA regardless of who the buyer is. Pair EXENTA_ART_21 with regime_key: "02".

curl -X POST "https://app.beel.es/api/v1/companies/{company_id}/invoices" \
  -H "Authorization: Bearer $BEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "STANDARD",
    "recipient": {
      "legal_name": "Acme Inc.",
      "alternative_id": { "type": "PASSPORT", "number": "M76543210", "country_code": "US" },
      "address": { "street": "5th Avenue", "number": "725", "postal_code": "10022", "city": "New York", "province": "NY", "country": "Estados Unidos", "country_code": "US" }
    },
    "lines": [
      {
        "description": "Export of goods",
        "quantity": 1,
        "unit": "unit",
        "unit_price": 200,
        "discount_percentage": 0,
        "main_tax": { "type": "IVA", "percentage": 0, "regime_key": "02" },
        "exemption_reason": "EXENTA_ART_21"
      }
    ]
  }'

Services to non-EU customers

By the general localisation rule, services to non-EU customers are not subject to Spanish IVA. Use NO_SUJETA_LOCALIZACION. The customer can be B2B or B2C — same classification.

curl -X POST "https://app.beel.es/api/v1/companies/{company_id}/invoices" \
  -H "Authorization: Bearer $BEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "STANDARD",
    "recipient": {
      "legal_name": "Acme Inc.",
      "alternative_id": { "type": "PASSPORT", "number": "M76543210", "country_code": "US" },
      "address": { "street": "5th Avenue", "number": "725", "postal_code": "10022", "city": "New York", "province": "NY", "country": "Estados Unidos", "country_code": "US" }
    },
    "lines": [
      {
        "description": "Professional services to US client",
        "quantity": 1,
        "unit": "project",
        "unit_price": 200,
        "discount_percentage": 0,
        "main_tax": { "type": "IVA", "percentage": 0, "regime_key": "01" },
        "exemption_reason": "NO_SUJETA_LOCALIZACION"
      }
    ]
  }'

Cheat sheet (international scenarios only)

This page is about cross-border scenarios. ISP (ISP_ART_84_2_*, S2) is a domestic Spanish mechanism for reverse charge on specific operations (construction, gold, etc.) — it does not apply to intra-EU or non-EU buyers. For ISP, see Tax classification > ISP.

Customer	Selling	`exemption_reason`	`main_tax.regime_key`	`alternative_id.type`
EU B2B (VIES)	Goods	`EXENTA_ART_25` (E5)	`01`	`NIF_IVA`
EU B2B (VIES)	Services	`NO_SUJETA_LOCALIZACION` (N2)	`01`	`NIF_IVA`
EU B2C (under OSS)	Anything	omit (S1)	`01`	`PASSPORT` / `COUNTRY_ID` / `OTHER_DOCUMENT`
EU B2C (OSS)	Anything	— (regime `17` alone → N2)	`17`	`PASSPORT` / `COUNTRY_ID` / `OTHER_DOCUMENT`
Non-EU	Goods	`EXENTA_ART_21` (E2)	`02`	`PASSPORT` / `COUNTRY_ID` / `OTHER_DOCUMENT`
Non-EU	Services	`NO_SUJETA_LOCALIZACION` (N2)	`01`	`PASSPORT` / `COUNTRY_ID` / `OTHER_DOCUMENT`

Common confusion: intra-EU B2B services are NO_SUJETA_LOCALIZACION (N2, Art. 69 LIVA), never ISP/S2 (Art. 84 LIVA). ISP is reserved for domestic Spanish operations — never for cross-border.

International customers

On this page