Create Invoice

POST/api/v1/invoices

Τhis endpoint allows you to create a new invoice. Oxygen PEPPOL API will automatically deliver the invoice to the C3 corner.

Top-level Invoice Attributes

The following table describes the top-level attributes that can be included in the request payload when creating a new invoice.

Attribute	BT	Type	Required	Description
id	BT-1	string	Required	The invoice number. Must be unique across all invoices.
issue_date	BT-2	string	Required	The date when the invoice was issued (format: Y-m-d).
invoice_type_code	BT-3	integer	Required	The type of invoice. Must be either 380 (Commercial Invoice) or 381 (Credit Note).
currency_code	BT-5	string	Required	The currency code of the invoice (ISO 4217, 3 characters).
tax_currency_code	BT-6	string	Optional	The tax currency code if different from the invoice currency (ISO 4217, 3 characters).
tax_point_date	BT-7	string	Optional	The date when the VAT becomes accountable.
due_date	BT-9	string	Optional	The date when payment is due.
buyer_reference	BT-10	string	Conditional	A reference provided by the buyer. Required if order_reference.id is not provided.
project_reference	BT-11	string	Conditional	Project reference (ADA code or PDE). Required for invoice type 380, prohibited otherwise.
contract_document_reference	BT-12	string	Required	Contract reference (ADAM code).
receipt_document_reference	BT-15	string	Optional	Receipt document reference.
despatch_document_reference	BT-16	string	Optional	Despatch advice reference.
originator_document_reference	BT-17	string	Optional	Originator document reference.
accounting_cost	BT-19	string	Optional	The accounting cost code.
payment_terms	BT-20	string	Optional	A textual description of the payment terms.
note	BT-22	string	Optional	Additional notes or comments about the invoice (max 65,535 characters).
order_reference		object	Optional	Reference to the order that this invoice is based on. See Order Reference.
billing_reference		array	Conditional	References to preceding invoices. Required for invoice type 5.1. See Billing Reference.
seller		object	Required	Information about the seller. See Seller.
buyer		object	Required	Information about the buyer. See Buyer.
payee		object	Optional	Information about the payee if different from seller. See Payee.
tax_representative		object	Optional	Tax representative information. See Tax Representative.
delivery		object	Conditional	Delivery information. Required for Greek sellers. See Delivery.
invoice_period		object	Optional	The invoice period. See Invoice Period.
payment_means		array	Optional	Payment means information. See Payment Means.
allowances		array	Optional	Document level allowances. See Allowances.
charges		array	Optional	Document level charges. See Charges.
totals		object	Required	Legal monetary totals. See Document Totals.
tax_totals		array	Required	Tax totals breakdown. See Tax Totals.
additional_documents		array	Optional	Additional supporting documents. See Additional Documents.
lines		array	Required	Invoice line items. See Invoice Lines.
attachment		file	Optional	PDF attachment (max 10MB, application/pdf).

Order Reference

Attribute	BT	Type	Required	Description
id	BT-13	string	Conditional	The order reference. Required if buyer_reference is not provided.
sales_order_id	BT-14	string	Optional	The sales order reference.

Billing Reference

Attribute	BT	Type	Required	Description
id	BT-25	string	Required	The invoice number being referenced.
issue_date	BT-26	string	Optional	The issue date of the referenced invoice.

Seller

Attribute	BT	Type	Required	Description
endpoint_id	BT-34	string	Required	The seller's electronic address identifier.
endpoint_scheme_id		string	Required	The scheme identifier for the seller's endpoint.
name	BT-28	string	Optional	The seller's trading name.
identification		array	Optional	Additional seller identifications. See Seller Identification.
legal_entity		object	Required	Seller legal entity information. See Seller Legal Entity.
address		object	Required	Seller postal address. See Seller Address.
tax_scheme		array	Optional	Seller tax scheme (max 2). See Seller Tax Scheme.
contact		object	Optional	Seller contact information. See Seller Contact.

Seller Identification

Attribute	BT	Type	Required	Description
id	BT-29	string	Required	The seller identifier.
scheme_id		string	Optional	The scheme identifier for the seller identifier.

Seller Legal Entity

Attribute	BT	Type	Required	Description
registration_name	BT-27	string	Required	The full legal name of the seller.
company_id	BT-30	string	Optional	The seller's company legal registration identifier.
scheme_id		string	Optional	The scheme identifier for the company ID.
company_legal_form	BT-33	string	Optional	The seller's legal form.

Seller Address

Attribute	BT	Type	Required	Description
street_name	BT-35	string	Optional	The main street name.
additional_street_name	BT-36	string	Optional	Additional street name or address line.
city_name	BT-37	string	Optional	The city or town name.
postal_zone	BT-38	string	Optional	The postal code.
country_subentity	BT-39	string	Optional	The country subdivision (e.g., region).
address_line	BT-162	string	Optional	Additional address line.
country	BT-40	string	Required	The country code (ISO 3166-1 alpha-2, 2 characters).

Seller Tax Scheme

Attribute	BT	Type	Required	Description
company_id	BT-31/BT-32	string	Required	The seller's tax registration identifier (VAT number).
scheme_id		string	Required	The tax scheme identifier.

Seller Contact

Attribute	BT	Type	Required	Description
name	BT-41	string	Optional	The contact point name.
telephone	BT-42	string	Optional	The contact telephone number.
email	BT-43	string	Optional	The contact email address.

Buyer

Attribute	BT	Type	Required	Description
endpoint_id	BT-49	string	Required	The buyer's electronic address identifier.
endpoint_scheme_id		string	Required	The scheme identifier for the buyer's endpoint.
name	BT-45	string	Optional	The buyer's trading name.
identification		array	Required	Buyer identifications (max 1). See Buyer Identification.
legal_entity		object	Required	Buyer legal entity information. See Buyer Legal Entity.
address		object	Required	Buyer postal address. See Buyer Address.
tax_scheme		array	Required	Buyer tax scheme (max 1). See Buyer Tax Scheme.
contact		object	Optional	Buyer contact information. See Buyer Contact.

Buyer Identification

Attribute	BT	Type	Required	Description
id	BT-46	string	Required	The buyer identifier.
scheme_id		string	Optional	The scheme identifier for the buyer identifier.

Buyer Legal Entity

Attribute	BT	Type	Required	Description
registration_name	BT-44	string	Required	The full legal name of the buyer.
company_id	BT-47	string	Optional	The buyer's company legal registration identifier.
scheme_id		string	Optional	The scheme identifier for the company ID.

Buyer Address

Attribute	BT	Type	Required	Description
street_name	BT-50	string	Optional	The main street name.
additional_street_name	BT-51	string	Optional	Additional street name or address line.
city_name	BT-52	string	Optional	The city or town name.
postal_zone	BT-53	string	Optional	The postal code.
country_subentity	BT-54	string	Optional	The country subdivision (e.g., region).
address_line	BT-163	string	Optional	Additional address line.
country	BT-55	string	Required	The country code (ISO 3166-1 alpha-2, 2 characters).

Buyer Tax Scheme

Attribute	BT	Type	Required	Description
company_id	BT-48	string	Required	The buyer's tax registration identifier (VAT number).
scheme_id		string	Required	The tax scheme identifier.

Buyer Contact

Attribute	BT	Type	Required	Description
name	BT-56	string	Optional	The contact point name.
telephone	BT-57	string	Optional	The contact telephone number.
email	BT-58	string	Optional	The contact email address.

Payee

Attribute	BT	Type	Required	Description
name	BT-59	string	Required	The name of the payee.
identification		array	Optional	Payee identifications (max 1). See Payee Identification.
legal_entity		object	Optional	Payee legal entity information. See Payee Legal Entity.

Payee Identification

Attribute	BT	Type	Required	Description
id	BT-60/BT-90	string	Required	The payee identifier.
scheme_id		string	Optional	The scheme identifier for the payee identifier.

Payee Legal Entity

Attribute	BT	Type	Required	Description
company_id	BT-61	string	Required	The payee's company legal registration identifier.
scheme_id		string	Optional	The scheme identifier for the company ID.

Tax Representative

Attribute	BT	Type	Required	Description
name	BT-62	string	Required	The tax representative party name.
tax_scheme		array	Required	Tax representative tax scheme (max 1). See Tax Representative Tax Scheme.
address		object	Required	Tax representative postal address. See Tax Representative Address.

Tax Representative Tax Scheme

Attribute	BT	Type	Required	Description
company_id	BT-63	string	Required	The tax representative's VAT identifier.
scheme_id		string	Required	The tax scheme identifier.

Tax Representative Address

Attribute	BT	Type	Required	Description
street_name	BT-64	string	Optional	The main street name.
additional_street_name	BT-65	string	Optional	Additional street name or address line.
city_name	BT-66	string	Optional	The city or town name.
postal_zone	BT-67	string	Optional	The postal code.
country_subentity	BT-68	string	Optional	The country subdivision (e.g., region).
address_line	BT-164	string	Optional	Additional address line.
country	BT-69	string	Required	The country code (ISO 3166-1 alpha-2, 2 characters).

Delivery

Attribute	BT	Type	Required	Description
party_name	BT-70	string	Required	The name of the delivery party.
location		object	Required	Delivery location information. See Delivery Location.
date	BT-72	string	Optional	The actual delivery date (format: Y-m-d).

Delivery Location

Attribute	BT	Type	Required	Description
id	BT-71	string	Optional	The delivery location identifier.
scheme_id	BT-71	string	Optional	The scheme identifier for the location identifier.
address		object	Required	Delivery address. See Delivery Address.

Delivery Address

Attribute	BT	Type	Required	Description
street_name	BT-75	string	Required	The main street name.
additional_street_name	BT-76	string	Optional	Additional street name or address line.
city_name	BT-77	string	Required	The city or town name.
postal_zone	BT-78	string	Required	The postal code.
country_subentity	BT-79	string	Optional	The country subdivision (e.g., region).
address_line	BT-165	string	Optional	Additional address line.
country	BT-80	string	Required	The country code (ISO 3166-1 alpha-2, 2 characters).

Invoice Period

Attribute	BT	Type	Required	Description
start_date	BT-73	string	Optional	The start date of the invoice period.
end_date	BT-74	string	Optional	The end date of the invoice period.
description_code	BT-8	string	Optional	The invoice period description code.

Payment Means

Attribute	BT	Type	Required	Description
payment_code	BT-81	string	Required	The payment means type code.
payment_description	BT-82	string	Optional	A textual description of the payment means.
payment_id	BT-83	string	Optional	The remittance information.
credit_transfer		object	Optional	Credit transfer information. See Credit Transfer.
card_account		object	Optional	Card account information. See Card Account.
direct_debit		object	Optional	Direct debit information. See Direct Debit.

Credit Transfer

Attribute	BT	Type	Required	Description
account_id	BT-84	string	Required	The payment account identifier (IBAN).
account_name	BT-85	string	Optional	The payment account name.
institution_id	BT-86	string	Optional	The payment service provider identifier (BIC).

Card Account

Attribute	BT	Type	Required	Description
pan	BT-87	string	Required	The payment card primary account number.
network_id		string	Required	The payment card network identifier.
holder_name	BT-88	string	Optional	The cardholder name.

Direct Debit

Attribute	BT	Type	Required	Description
id	BT-89	string	Optional	The mandate reference identifier.
payer_account_id	BT-91	string	Optional	The debited account identifier.

Allowances

Attribute	BT	Type	Required	Description
amount	BT-92	decimal	Required	The allowance amount.
base_amount	BT-93	decimal	Optional	The base amount used to calculate the allowance.
percent	BT-94	decimal	Optional	The percentage applied to calculate the allowance.
tax_category		object	Required	Tax category for the allowance. See Allowance Tax Category.
reason	BT-97	string	Conditional	The reason for the allowance. Required if reason_code is not provided.
reason_code	BT-98	string	Conditional	The allowance reason code. Required if reason is not provided.

Allowance Tax Category

Attribute	BT	Type	Required	Description
id	BT-95	string	Required	The tax category code.
percent	BT-96	decimal	Required	The tax rate percentage.

Charges

Attribute	BT	Type	Required	Description
amount	BT-99	decimal	Required	The charge amount.
base_amount	BT-100	decimal	Optional	The base amount used to calculate the charge.
percent	BT-101	decimal	Optional	The percentage applied to calculate the charge.
tax_category		object	Required	Tax category for the charge. See Charge Tax Category.
reason	BT-104	string	Required	The reason for the charge.
reason_code	BT-105	string	Optional	The charge reason code.

Charge Tax Category

Attribute	BT	Type	Required	Description
id	BT-102	string	Required	The tax category code.
percent	BT-103	decimal	Required	The tax rate percentage.

Document Totals

Attribute	BT	Type	Required	Description
total_net_amount	BT-106	decimal	Required	Sum of invoice line net amounts.
total_allowance_amount	BT-107	decimal	Optional	Sum of allowances on document level.
total_charge_amount	BT-108	decimal	Optional	Sum of charges on document level.
total_tax_exclusive_amount	BT-109	decimal	Required	Invoice total amount without VAT.
total_tax_inclusive_amount	BT-112	decimal	Required	Invoice total amount with VAT.
total_prepaid_amount	BT-113	decimal	Optional	Sum of paid amounts.
rounding_amount	BT-114	decimal	Optional	The rounding amount.
total_payable_amount	BT-115	decimal	Required	The amount to be paid.

Tax Totals

Attribute	BT	Type	Required	Description
tax_amount	BT-110/BT-111	decimal	Required	The total tax amount.
tax_currency		string	Required	The tax currency code (use BT-5 or BT-6).
subtotals		array	Required	Tax subtotal breakdown. See Tax Subtotals.

Tax Subtotals

Attribute	BT	Type	Required	Description
taxable_amount	BT-116	decimal	Required	The taxable amount for this tax category.
tax_amount	BT-117	decimal	Required	The tax amount for this tax category.
tax_category		object	Required	Tax category details. See Tax Subtotal Category.

Tax Subtotal Category

Attribute	BT	Type	Required	Description
id	BT-118	string	Required	The tax category code.
percent	BT-119	decimal	Optional	The tax rate percentage.
exemption_reason	BT-120	string	Optional	The tax exemption reason text.
exemption_reason_code	BT-121	string	Optional	The tax exemption reason code.

Additional Documents

Attribute	BT	Type	Required	Description
id	BT-122	string	Required	The document identifier.
scheme_id		string	Optional	The scheme identifier for the document identifier.
document_type_code	BT-18	string	Optional	The document type code.
document_description	BT-123	string	Optional	A description of the document.
attachment		object	Optional	Document attachment information. See Document Attachment.

Document Attachment

Attribute	BT	Type	Required	Description
uri	BT-124	string	Optional	External document URI.
embed	BT-125	string	Optional	Embedded document (base64).
embed_mime_code		string	Conditional	MIME code of embedded document. Required if embed is provided.
embed_filename		string	Conditional	Filename of embedded document. Required if embed is provided.

Invoice Lines

Attribute	BT	Type	Required	Description
id	BT-126	string	Required	The invoice line identifier. Must be unique within the invoice.
note	BT-127	string	Optional	A note about the invoice line (max 65,535 characters).
document_reference		object	Optional	Document reference for the line. See Line Document Reference.
quantity	BT-129	decimal	Required	The invoiced quantity.
unit_code	BT-130	string	Required	The unit of measure code.
net_value	BT-131	decimal	Required	The line net amount.
order_line_reference	BT-132	string	Optional	The order line reference.
accounting_cost	BT-133	string	Optional	The accounting cost code for the line.
invoice_period		object	Optional	Line invoice period. See Line Invoice Period.
allowances		array	Optional	Line level allowances. See Line Allowances.
charges		array	Optional	Line level charges. See Line Charges.
price_details		object	Required	Price information. See Price Details.
item		object	Required	Item information. See Item.
properties		array	Optional	Item properties. See Item Properties.

Line Document Reference

Attribute	BT	Type	Required	Description
id	BT-128	string	Optional	The document reference identifier.
scheme_id		string	Optional	The scheme identifier for the document identifier.
document_type_code	BT-128	string	Optional	The document type code.

Line Invoice Period

Attribute	BT	Type	Required	Description
start_date	BT-134	string	Optional	The start date of the line invoice period.
end_date	BT-135	string	Optional	The end date of the line invoice period.

Line Allowances

Attribute	BT	Type	Required	Description
amount	BT-136	decimal	Required	The line allowance amount.
base_amount	BT-137	decimal	Optional	The base amount used to calculate the allowance.
percent	BT-138	decimal	Optional	The percentage applied to calculate the allowance.
reason	BT-139	string	Optional	The reason for the allowance.
reason_code	BT-140	string	Optional	The allowance reason code.

Line Charges

Attribute	BT	Type	Required	Description
amount	BT-141	decimal	Required	The line charge amount.
base_amount	BT-142	decimal	Optional	The base amount used to calculate the charge.
percent	BT-143	decimal	Optional	The percentage applied to calculate the charge.
reason	BT-144	string	Optional	The reason for the charge.
reason_code	BT-145	string	Optional	The charge reason code.

Price Details

Attribute	BT	Type	Required	Description
price_amount	BT-146	decimal	Required	The item net price (per unit).
discount_amount	BT-147	decimal	Optional	The item price discount amount.
base_amount	BT-148	decimal	Optional	The item gross price.
base_quantity	BT-149	decimal	Optional	The item price base quantity.
base_quantity_unit_code	BT-150	string	Optional	The item price base quantity unit of measure code.

Item

Attribute	BT	Type	Required	Description
name	BT-153	string	Required	The item name (max 1000 characters).
description	BT-154	string	Optional	The item description.
seller_assigned_id	BT-155	string	Optional	The item seller's identifier.
buyer_assigned_id	BT-156	string	Optional	The item buyer's identifier.
standard_id	BT-157	string	Optional	The item standard identifier.
standard_scheme_id		string	Conditional	The scheme identifier for standard ID. Required if standard_id is provided.
classifications		array	Required	Item classifications. See Item Classifications.
origin_country	BT-159	string	Optional	The item country of origin (ISO 3166-1 alpha-2).
tax_category		object	Required	Item tax category. See Item Tax Category.

Item Classifications

Attribute	BT	Type	Required	Description
code	BT-158	string	Required	The item classification code.
list_id		string	Required	The item classification identifier.
version_id		string	Optional	The item classification version.

Item Tax Category

Attribute	BT	Type	Required	Description
id	BT-151	string	Required	The invoiced item VAT category code.
percent	BT-152	decimal	Required	The invoiced item VAT rate percentage.

Item Properties

Attribute	BT	Type	Required	Description
name	BT-160	string	Required	The item attribute name.
value	BT-161	string	Required	The item attribute value.

Example Request

Below is an example of a request to create a new invoice. Please ensure to replace {token} with your actual authentication token. The data placeholder represents the JSON payload containing the invoice details and an example is provided below.

Example using cURL

curl https://sandbox-peppol.oxygen.gr/api/v1/invoices \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{{ data }}'

data

{
  "invoice_number": "888888888|14/01/2026|0|1.1|ΤΔΑ|14",
  "issue_date": "2026-01-14",
  "invoice_type_code": 380,
  "currency_code": "EUR",
  "buyer_reference": "REF-2026-001",
  "project_reference": "ADA-123456",
  "seller": {
    "name": "ACME Corporation",
    "legal_entity": {
      "registration_name": "ACME Corporation SA",
      "company_id": "123456789"
    },
    "address": {
      "street_name": "Main Street",
      "city_name": "Athens",
      "postal_zone": "10563",
      "country": "GR"
    },
    "tax_scheme": [
      {
        "company_id": "999999999",
        "scheme_id": "VAT"
      }
    ]
  },
  "buyer": {
    "endpoint_id": "9933888888888",
    "endpoint_scheme_id": "0088",
    "name": "Client Company Ltd",
    "legal_entity": {
      "registration_name": "Client Company Ltd"
    },
    "address": {
      "street_name": "Business Avenue",
      "city_name": "Thessaloniki",
      "postal_zone": "54625",
      "country": "GR"
    },
    "tax_scheme": [
      {
        "company_id": "888888888",
        "scheme_id": "VAT"
      }
    ]
  },
  "delivery": {
    "party_name": "Client Company Ltd",
    "location": {
      "address": {
        "street_name": "Business Avenue",
        "city_name": "Thessaloniki",
        "postal_zone": "54625",
        "country": "GR"
      }
    }
  },
  "lines": [
    {
      "id": "1",
      "quantity": 10,
      "unit_code": "C62",
      "net_value": 1000.00,
      "item": {
        "name": "Professional Services",
        "tax_category": {
          "id": "S",
          "percent": 24
        }
      },
      "price_details": {
        "price_amount": 100.00
      }
    }
  ],
  "totals": {
    "total_net_amount": 1000.00,
    "total_tax_exclusive_amount": 1000.00,
    "total_tax_inclusive_amount": 1240.00,
    "total_payable_amount": 1240.00
  },
  "tax_totals": [
    {
      "tax_amount": 240.00,
      "tax_currency": "EUR",
      "subtotals": [
        {
          "taxable_amount": 1000.00,
          "tax_amount": 240.00,
          "tax_category": {
            "id": "S",
            "percent": 24
          }
        }
      ]
    }
  ]
}

Example Response

Example Response

{
  "id": "01kev9gvvrwggfmbjb3zg4qvb3",
  "invoice_number": "888888888|14/01/2026|0|1.1|ΤΔΑ|14",
  "issue_date": "2026-01-14",
  "buyer_reference": "REF-2026-001",
  "buyer_tin": "888888888",
  "buyer_name": "Client Company Ltd",
  "transmission" : {
    "status_code": 202,
    "error_message": null
  },
  "url": "https://sandbox-peppol.oxygen.gr/invoices/01kev9gvvrwggfmbjb3zg4qvb3/preview"
}

Response Fields

The response of the Create Invoice endpoint includes the following fields:

Field	BT	Type	Description
id		string	The unique identifier of the created invoice.
invoice_number	BT-1	string	The invoice number as provided during invoice creation.
issue_date	BT-2	string	The issue date of the created invoice.
buyer_reference	BT-10	string	The buyer reference as provided during invoice creation.
buyer_tin	BT-48	string	The Buyer's VAT identifier.
buyer_name	BT-44	string	The Buyer's registration name.
transmission		object	An object containing the status of the invoice transmission to the C3 corner.
url		string	A URL to preview the created invoice.

Transmission Object Fields

The transmission object in the response includes the following fields:

Field	Type	Description
status_code	int	The current status code of the invoice transmission to the C3 corner.
error_message	string	An error message providing additional context if the invoice encountered an error during transmission.

Response Codes

When creating invoices, the API will return the following response codes to indicate the result of the operation:

Response Code	Description
201	Invoice created successfully.
401	Unauthenticated. Invalid or missing authentication token.
403	Unauthorized. The authenticated user does not have permission to create invoices.
422	Unprocessable Entity. The invoice could not be processed due to validation errors.
423	If the invoice with the same invoice_number is already being processed.

Transmission Status Code

The response of the Create Invoice includes fields related to the transmission of the invoice to the C3 corner. You can check the transmission object in the response to determine the current status of the invoice transmission.

Field	Description
202	The invoice has been accepted for processing by the C3 corner. The error_message field will be null.
422	The invoice was rejected due to validation errors. The error_message field will contain details about the errors.
500	An internal server error occurred during transmission. The error_message fields will provide more information.

Learn more about invoice transmission model