Storecove | API Documentation

If you have any questions, please contact us at apisupport@storecove.com.

Subscribe to our statuspage on https://storecove.statuspage.io/

1. Introducing Storecove

Storecove is the only international operating Service Providers that offers a one-stop e-invoicing solution for eReporting (CTC - for many countries in the world) and eInvoicing (sending your invoice - via OpenPeppol, DBNAlliance, legacy EDI networks or email). Large companies and ERP systems can connect with all worldwide available e-invoicing networks. By supporting every global invoice format we ensure that you only need to connect through a single connection with a single data format. Development departments worldwide love our solution. Try us today and test for free!

1.1. Getting Started

This guide will help you get started with the Storecove API in under 5 minutes.

1.1.1. Register for API access

To obtain access to our developer sandbox API environment, request a developer sandbox account here:

E-invoicing API

1.1.2. Create an API key

Create a new API key by clicking the "Create New API Key" button.

1.1.3. Make your first API call

Create a file "discovery.json" with the following contents (these are both Storecove Test Identifiers):

{
  "documentTypes": ["invoice"],
  "network": "peppol",
  "metaScheme": "iso6523-actorid-upis",
  "scheme": "de:lwid",
  "identifier":"10101010-STO-10"
}

or, for the DBNAlliance network, use

{
  "documentTypes": ["invoice"],
  "network": "dbnalliance",
  "metaScheme": "iso6523-actorid-upis",
  "scheme": "gln",
  "identifier":"1200109963131"
}

Call the API with your API key to check whether this participant identifier can receive invoices on the exchange network of choice. The example below will perform the check:

curl \
-X POST "https://api.storecove.com/api/v2/discovery/receives" \
-H "Accept: application/json" \
-H "Authorization: Bearer API_KEY_HERE" \
-H "Content-Type: application/json" \
--data @discovery.json

Swap the "API_KEY_HERE" for the API key you created. Don’t remove the "Bearer" prefix!

Since Storecove can receive invoices on both identifiers, the response is

{
  "code":  "OK",
  "email": false
}

The "code" field with value "OK" indicates this identifier can receive invoices. Ignore the "email" property for now.

1.1.4. Create a sender

The first step in sending an invoice is to create a sender. This sender is called a "LegalEntity". LegalEntities can both send and receive, but for now we will focus on their sending role. Although the LegalEntity we are creating now can contain dummy data, you should carefully choose the LegalEntity’s country, because this will be important for the contents of the invoice.

For SG, IT, FI (Finvoice), ES (Face, FaceB2B) and PT additional setup steps are required and so to test this you need to contact us first.

Creating a LegalEntity is done in the UI, on

https://app.storecove.com/senders

In the UI you will be guided as to which participant identifiers to add to the LegalEntity.

Once created you will see the legalEntityId in the UI. You will need this id in the next step. Note that it can take up to a day for Storecove to approve the LegalEntity.

1.1.5. Send your first invoice

Having created our sender, we now choose the sender/receiver combination and create a file "invoice.json" with the appropriate contents.

We have a list of test identifiers that we advertise on the different exchange networks that these test invoices will get sent to. So simply click on the right scenario and copy/paste!

Receiver

Sender

EU/EEA

AU/NZ

World

EU/EEA

Any EU => SG (export)

AU/NZ

FI => FI (Try Peppol, otherwise Finvoice)

IN => DE

IN => IN (same state)

IN => IN (between states)

World

Swap the "LEGAL_ENTITY_ID" in the JSON for the id you received when creating the LegalEntity.

Next use this API call to send the invoice:

curl \
-X POST "https://api.storecove.com/api/v2/document_submissions" \
-H "Accept: application/json" \
-H "Authorization: Bearer API_KEY_HERE" \
-H "Content-Type: application/json" \
--data @invoice.json

The result will be similar to:

{
  "guid":  "c65d43d1-4b44-40a9-8926-6743f9fc90b2"
}

1.1.6. Sent! (Retrieve the Sending Evidence)

Congratulations! You’ve successfully submitted an invoice for sending. If you have configured Webhooks we will let you know the progress of the sending process that way. If you have not yet configured any webhooks, you can track the progress in the UI, on

https://app.storecove.com/en/invoice_submissions/api

When you see it has been successfully sent (or you have received a webhook, but in this Getting Started guid we have not done that) you can retrieve the evidence for that by calling

curl \
-X GET "https://api.storecove.com/api/v2/document_submissions/c65d43d1-4b44-40a9-8926-6743f9fc90b2/evidence" \
-H "Accept: application/json" \
-H "Authorization: Bearer API_KEY_HERE" \
-H "Content-Type: application/json"

(Change the GUID to the one you received when sending the invoice.) This will give you the exact invoice sent, as well as the digital signature from the receiving accesspoint or tax authority. Or, if the invoice was sent via email, it will give you the full email that was sent with its attachments as well are response from the receiving SMTP server.

What if my Customer is not on one of the Exchange networks (Peppol, DBNAlliance)?

Then we can send an email with an electronic invoice attachment that is appropriate for the country your Customer is in. For instance, in de Germany we would send a ZUFGFeRD attachment, in France Facture-X and in Italy a FatturaPA. For India, the GSTN-signed JSON with a PDF that includes the QR code will be attached. Your receiver will know how to process these!

To test the email scenario, simply include a valid email address in the examples above and leave the "eIdentifiers" array empty, like this:

{
  "routing":  {
    "emails": [
      "test@example.com"
    ],
    "eIdentifiers": []
  }
}

The email address must be valid. Do not test with invalid email addresses.

We recommend using the account you’ve just created for all your development purposes. When you’re ready to launch your integration, create a new account and reach out to our support to convert to 'production' API keys!

2. Using the API

The Storecove API provides all your e-invoicing and Peppol integration needs. This section outlines everything you need to use the V2 API, which is available at https://api.storecove.com/api/v2/.

You cannot click this URL, because it is an API endpoint, not a page that can be viewed in a browser.

2.1. API keys

To call the Storecove V2 API, you will first need an API key from the developer portal. An API key represents your application, so if you’re building multiple solutions you’ll need multiple keys.

API keys secrets, so do not publish them in a public config such as to frontend JavaScript applications.

To do this, navigate to API Keys in your Storecove admin panel. You will typically need only one, however you can create multiple for use with different environments, migrations or when rotating secrets.

The API Key must be provided in the Authorization header using the Bearer scheme for all API requests.

Authorization: Bearer API_KEY_HERE

For instance, a curl request could look like

curl \
-X POST "https://api.storecove.com/api/v2/legal_entities" \
-H "Accept: application/json" \
-H "Authorization: Bearer API_KEY_HERE" \
-H "Content-Type: application/json" \
-d "{ \"party_name\": \"Test Party\", \"line1\": \"Test Street\", \"city\": \"Test City\", \"zip\": \"Zippy\", \"country\": \"NL\", \"tenant_id\": \"my_id\"}"

These headers are safe inside the TLS tunnel that protects the Storecove API.

2.2. Webhooks

Webhooks allow you to be notified of certain events taking place on the Storeove platform. There are two types:

Push mode

Push mode allows you to receive notifications without the need for polling. They consist of a URL that is called with a POST body, optionally protected with HTTP Basic Authentication or a custom HTTP header.

You should reply with an HTTP OK (200) to the POST. If another status code is presented, or we fail to reach the specified URL, we will retry again at a later time for a total of 5 days.

We will keep calling the webhook until we receive an HTTP 200 from you, but only for 5 days.

During development, the following site may prove useful for viewing the webhooks we call:
```
https://webhook.site
```
Pull mode

Pull mode (aka FIFO queue) webhooks are typically used when the system that needs to receive them does not have a service to receive them. In pull mode, you use the

GET a WebhookInstance

endpoint to retrieve a new webhook off the queue. After processing it successfully, DELETE it using

DELETE a WebhookInstance

and GET the next one. When you receive an HTTP 204 response, the queue is empty and your polling process can sleep for a while.

2.3. API tools

There are several types of tools that can speed up your solution development. We publish an Open API v2 (a.k.a. Swagger) specification that allows you to generate client libraries and test API calls using API clients like Postman.

2.3.1. Client Libraries

The API is RESTful and communicates through JSON, so you can easily create your own client if we don’t have one ready to go and you don’t want to leverage the OpenAPI 2.0 API specification (see below).

The easiest way to create a client for your favourite language is by leveraging our OpenAPI 2.0 (previously known as Swagger) specification, which can be found on

https://api.storecove.com/api/v2/openapi.json

There are many generic REST clients for available for different platforms. However, if you wish to roll your own, or would like to quickly generate the model classes, you could use Swagger Codegen.

2.3.2. Postman

Using our OpenAPI 2.0 specification, it is easy to test drive the API, for instance with Postman:

https://www.postman.com/downloads/

Click "Import," select "Import From Link," and copy/paste our OpenAPI 2.0 specification URL:

https://api.storecove.com/api/v2/openapi.json

Next, click on the "Headers" tab and copy/paste the API token. You are now ready to test drive the API!

2.3.3. Swagger Codegen

This tool makes it easy to to generate a client library in your favorite language:

https://github.com/swagger-api/swagger-codegen

First, download the lastest version 2 Java jar:

wget --output-document=swagger-codegen-cli.jar https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.24/swagger-codegen-cli-2.4.24.jar

Next, create the client library (in this example we generate a C# library):

java -jar swagger-codegen-cli.jar generate -i https://api.storecove.com/api/v2/openapi.json -l csharp -o csharp

Language support is extensive, amongst others:

C# (csharp, csharp-dotnet2)
Java (java-pkmst, java-play-framework, jaxrs-resteasy-eap)
Node.js (nodejs-server)
Objective-C (objc)
Android (android)
Perl (perl)
PHP (php, php-symfony, php-silex)
Python (python)
Many others, execute:

java -jar swagger-codegen-cli.jar langs

2.4. camelCase or snake_case?

When POSTing data, we allow both the use of (lower) camelCase (sometimes called dromedaryCase ) and snake_case (see Multiple-word identifier formats). So if you see them used interchangeably in our documentation, that is not something to worry about. Choose your favourite way!

When you GET data, we always send you snake_case for object properties.

3. Building Your Solution

3.1. Environments

We have two different environments:

Sandbox
Production

The Sandbox environment allows you to implement the Storecove solution. It has the following features:

Webhook simulation

It allows you to simulate webhooks. Webhooks are how we notify you of events that have taken place asynchronously (see Webhooks). You can simulate receiving a document, or receiving status feedback on a document that you have sent.
Test exchange networks

The sandbox environment is linked to test exchange networks or tax authorities:
- OpenPeppol
- DBNAlliance
- Italy SDI (simulated)
- India GSTIN
- Poland KSeF
- Portugal eSPap
- Spain FACe and FACeB2B
- Finland Finvoice
So you can use the sandbox environment to see what would happen in the production environment.

We recommend always having both environments. So you start in sandbox and then for production you create a second account. That way, you can continue to test and develop without affecting your production environment.

3.2. Legal Entities

3.2.1. Actors

Legal entities are the actors between whom documents are exchanged. If you are sending an invoice, the sender is a legal entity and the receiver is a legal entity.

LegalEntities have two important properties:

{
  "acts_as_sender": true,
  "acts_as_receiver": true
}

When the flag "acts_as_receiver is set, it’s identifiers will be advertised on the Exchange networks OpenPeppol and/or DBNAlliance. That means you will automatically start receiving documents (usually invoices) via those networks. When the flag "acts_as_sender" is set, the LegalEntity can also send documents. So with a single LegalEntity, you can send documents to the whole world as well as receive documents from the whole world!

LegalEntities are created in the user interface on https://app.storecove.com/.

3.2.2. Identifiers

Types

There are three types of identifiers involved, although not always all of them:

Business Identifiers
- Legal Identifiers
  
  A legal identifier identifies the legal entity from a legal perspective. It can be a local chambre of commerce number, or a DUNS, GLN, etc. However, in many countries the tax identifier is also the legal identifiers. In that case you don’t need to set this up separately.
- Tax Identifiers
  
  A tax identifier identifies the legal entity from a tax perspective. In the EU, all tax identifiers are VAT numbers and are prefixed with the ISO3166-2 country code, e.g. "IT12345678901". In India, the tax identifier is issued by the state in which the LegalEntity resides. It’s first two digits are always the numercial code of the state that issued it.
Routing identifiers

A routing identifier is used to route the electronic document to the receiver. The good news is that, with a few exceptions, most routing identifiers are business identifiers! An obvious exception is an email address. When the invoice is routed to an email address, that is not one of the business identifiers. But most of the time, you do not need to store routing identifiers separately.

Structure

Identifiers consist of two parts:

scheme
identifier

The scheme defines the type of identifier. For instance, the Italian VAT number "IT12345678901" has scheme IT:IVA. A New Zealand tax identifier has the scheme "NZ:GST". Most schemes are prefixed with an ISO3166-2 country code, but not all. Examples are LEI (the global Legal Entity Identifier) GLN and DUNS.

Which identifiers for my LegalEntity?

After creating the LegalEntity, you will need to add one or more business identifiers. The relevant ones will automatically be advertised on the various exchange networks by us. (If you want to create sending-only LegalEntities, please contact us.)

The list of identifers to add to your LegalEntity can be found here:

Sender Identifiers

3.2.3. Additional Tax Identifiers

There are two legal territories where additional tax identifiers are relevant:

EU

In the EU, when (1) a LegalEntity sends an invoice to a consumer in a receiver country different from the sender country and (2) that LegalEntity is above the threshold for that receiver country, the sender is required to apply for a VAT number in the receiver country. And that VAT number must be used in the invoice.
IN

In India, when a LegalEntity sends an invoice to a receiver in a state different from the sender state, the sender is required to apply for a GST number in the receiver state. And that GST number must then be used in the invoice.

This is where additional tax identifiers come in. The LegalEntity will already have a primary tax identifier, which is the one that was issued by the country in which it is located. On top of that, AdditionalTaxIdentifiers can be created created according to the following rules:

EU
- You can have only one AdditionalTaxIdentifier per EU country
- You cannot create an AdditionalTaxIdentifier for the LegalEntity’s home country, because that is the LegalEntity’s primary tax identifier.
IN
- You can have only one AdditionalTaxIdentifier per state
- You cannot create an AdditionalTaxIdentifier for the LegalEntity’s home state, because that is the LegalEntity’s primary tax identifier.

To activate this feature, for invoices that require the use of an AdditionalTaxIdentifier, you must set the "consumerTaxMode" property in the Invoice object to true.

3.3. Sending Documents

3.3.1. Sending Workflow

Invoice Sending Workflow

The sending workflow for invoices consists of the following phases:

CTC Compliance
Tax Compliance
Exchange Networks
Static Routes
Email

1. CTC Compliance

In the compliance phase, we look at requirements that may exist in certain countries for sending invoices. The following CTC models exist:

V-flow

In this flow, the tax authority is the central organization through whom the invoice is sent. See, for instance, Italy:

Note that you can simply provide the Storecove JSON and we will take care of generating the format required by the tax authority. For Italy we will generate the FatturaPA format.
Other countries that have this model are
- Poland
- Romania
- France (OD model; to be launched in 2025)
Y-flow

There are two types of Y-flow:
1. Hard Clearance Y
  
  In the hard clearance Y-flow, the invoice must first be approved by a tax authority. Usually, this involves receiving a digital signature, often in the form of a QR-code. When we receive a QR-code, this is automatically stamped inside any PDF, if present and special anchors are present in the PDF (for details, see PDF Stamping). We will also ensure the digital signature is added to any eInvoice, e.g. when sending via OpenPeppol or DBNAlliance.
  India is an example of a country with this flow:
2. Reporting Y
  
  In the reporting Y-flow, the tax authority wants to receive a summary or full copy of the invoice. Although this can be done after sending, it is our policy to first successfully send to the tax authority, before delivery to the receiver. This prevents cases where there are issues with reporting the invoice to the tax authority, but it has already been sent.

If a CTC-reporting requirement exists in a country, and you have the necessary addon active in your subscription, the flow will be automatically applied. (Note that in sandbox mode all addons are considered to be active.)

2. Tax Compliance

We work closely with our partner (VATCalc) to ensure the invoice will be part of your tax filing (for example mini SAF-T). An invoice that was successfully eReported (if required) is in this step automatically made part of you next tax filing. This way you will never see differences between your tax filing and eInvoicing! Contact us if you are interested in learning more about how this works.

3. Exchange networks

If the invoice was not sent through one of the previous two phases, exchange networks are next on the list. We currently support OpenPeppol and the US-based DBNAlliance. If the receiver is a member of one of these exchange networks, the invoice will automatically be transported through that network.

4. Static routes

We support a limited number of statically routed networks. Static routes are discouraged, because they require one-to-one setup between the sender and the receiver and are therefore not as scaleable as exchange networks. If you have a receiver on a statically-routed network, we recommend you first try to migrate the receiver to an exchange network. However, if that is not possible, statically routed networks can be supported. Below is an example for the legacy Finvoice network commonly used in Finland:

5. Email

If none of the previous phases resulted in the invoice being sent, and an email address was provided in the routing object, the invoice will be sent to that email address. That email will contain one or more attachments, the contents of which depends on the country of the receiver. For instance, in Germany/France we will send ZUGFeRD/Factur-X, in Italy FatturaPA, etc.. Also the language of the email will be appropriate for the country of the receiver.

If you do not provide an email address, and we could not send the invoice in any other way, we will respond with an HTTP 422 Unprocessable Entity with a body "No action taken".

3.3.2. Sending a document

There are two main ways to submit a document to be sent:

A JSON object that contains the document data
(only for invoices) A Base64 encoded string embedded in a JSON that contains the document data in a certain syntax, such as UBL, CII, SAP IDOC, Microsoft Dynamics/Business Central, cXML, etc. In this case, we will parse the document and transform it into the JSON object our API requires, so it is an additional tranformation step.

The following document types can currently be sent:

Invoice
Invoice Reponse
Order

Invoice

The Invoice document (Invoice) has several sections:

Tax system
General data
Modifiers
Parties
References
Delivery details
Payment
Allowances and charges
Invoice lines
Amounts

Each will be discussed in more detail below.

Tax System

The tax system of an invoice is the first and most important choice when creating an invoice. There are two tax systems that can be used:

tax_line_percentages
tax_line_amounts

The TL;DR is that most receivers only support tax_line_percentages, so if at all possible, create invoices using that tax system.

To explain the difference, let’s look at an example. A typical invoice with three lines and one allowance and one charge could look like this:

tax_line_percentages
Item	Excluding tax	Tax %	Tax amount
Line 1	$819.50	15%
Line 2	$2,739.00	15%
Line 3	$6,600.00	15%
Charge 1	$40.00	25%
Allowance 1	-$461.75	15%
Total	$9,736.75

TaxSubtotal 15%	$9,696.75	15%	$1,454.51
TaxSubtotal 25%	$40.00	25%	$10.00
Total Tax			$1,464.51

Total including tax	$11,201.26

The same invoice in tax system tax_line_amounts would be:

tax_line_amounts
Item	Excluding tax	Tax %	Tax amount
Line 1	$819.50	15%	$122.93
Line 2	$2,739.00	15%	$410.85
Line 3	$6,600.00	15%	$990.00
Charge 1	$40.00	25%	$10.00
Allowance 1	-$461.75	15%	-$69.26
Total	$9,736.75

TaxSubtotal 15%	$9,696.75	15%	$1,454.52
TaxSubtotal 25%	$40.00	25%	$10.00
Total Tax			$1,464.52

Total including tax	$11,201.27

Notice the 1ct difference in the 15% tax subtotal and then in the invoice total. If the invoice data you give us is tax_line_amounts, but the receiver only supports tax_line_percentages, we will convert this as follows:

tax_line_amounts – converted
Item	Excluding tax	Tax %	Tax amount
Line 1	$819.50	15%	$122.93
Line 2	$2,739.00	15%	$410.85
Line 3	$6,600.00	15%	$990.00
Charge 1	$40.00	25%	$10.00
Allowance 1	-$461.75	15%	-$69.26
Rounding line 15%	-$0.07	15%	-$0.01
Total	$9,736.68

TaxSubtotal 15%	$9,696.68	15%	$1,454.51
TaxSubtotal 25%	$40.00	25%	$10.00
Total Tax			$1,464.51

Total including tax	$11,201.19
Payable rounding amount	-$0.08
Total amount payable	$11,201.27

General Data

Under general invoice data we find:

invoice number
issue date
tax date

Note that in many countries the tax date must be the same as the issue date, so if you provide this make sure it is correct.
due date
period
note
issue reaons

The issue reasons are only used in invoices for Italian receivers. They correspond to the <Causale> elements.

Modifiers

Preferred Invoice Type

When you send a creditnote, you should simply provide negative amounts to make for a negative invoice total. When we see the invoice has a negative total, we will normally try to send it as a creditnote. But whether that is actually done depends on the receiver. If the invoice is sent via an exchange network such as OpenPeppol, we will send a creditnote if the receiver advertises that. Otherwise, we will send an invoice with negative amounts. When sending via email, we will do it in a way that is customary in the receiver’s country.

In some cases, even though the total invoice amount is negative, you may prefer to send a regular invoice anyway. For instance, energy providers may send a regular invoice with a single negative adjustment that is larger than the regular invoice amount and thus the total become negative. But it is still considered a regular invoice, not a creditnote. That beharvious can be controlled through this property.

Self Billing Mode

Self Billing Mode essentially means the sender and receiver are reversed. The sender creates an invoice on behalf of the receiver and send it. We currently only support this via email. The OpenPeppol network supports self billing only for AU/NZ and JP. We only support this for invoices inside a country, i.e. not for cross-border invoices.

Parties

We support the following parties involved in the invoice:

the sender
the receiver

Sender

The sender ("AccountingSupplierParty" in UBL parlance) is identified by the id of the LegalEntity that you created. So most sender data for the sender is taken from that. However, there are a few fields that you can control dynamically per invoice, all related to the contact. That allows you to specify different contact details per invoice, for example when invoices are issued by different departments that have different contact points in case of questions.

Receiver

The receiver ("AccountingCustomerParty" in UBL parlance) consists of the following blocks:

name
address
identifiers
contact

The identifiers should contain (where applicable) the legal identifier and the tax identifier of the receiver, according to this list:

Receiver Identifiers

References

The references array is a flexible way to link the invoice to other documents, like a purchase order, delivery note, other invoice, etc. The most important one is the "purchase_order" which becomes the "OrderReference" element in a UBL invoice and which is what most governments use to automatically process the invoice. Without this, many invoices will get rejected.

The accounting cost field helps the receiver book the invoice against the correct general ledger account.

Delivery Details

Details regarding the delivery: to whom, where, when and how much.

Payment

Adding payment methods is relevant both when the invoice is still to be paid and when the invoice has already been paid. In the latter case, use the "prepaidAmount" property and set that to the amount already paid.

Not all formats allow multiple payment methods and not all payment methods are allowed in all formats. We will automatically ensure the most relevant are included, subject to what is possible. See also Globalization.

Invoice Lines

Invoice lines are complex objects in and of themselves. They consist of the following sections:

Textual Information
Amounts
Taxes
Period
Identifications
Key/value Pairs

Textual Information

An invoice line has a name and a description. The name is a short description of the item. The Description allows for describing the item and its features in more detail than the name.

Amounts

You need to make sure that

\$p \times q + "allowances" - "charges" = "amount excluding tax"\$

The price and quantity can be specified up to 8 decimals. It is important not to round these down so the multiplication is precise. Otherwise, many invoice formats will reject your invoice.

Taxes

Multiple Tax items is allowed only for IN (India) taxes. All other countries can only have a single Tax item in this array. For tax system "tax_line_percentages" a typical EU tax array might look like

[
  {
    "country": "DE",
    "percentage": 6.0,
    "category": "standard"
  }
]

and for India:

[
  {
    "country": "IN",
    "percentage": 14.0,
    "category": "sgst"
  },
  {
    "country": "IN",
    "percentage": 14.0,
    "category": "igst"
  }
]

We will automatically package the data in such a way that it can be automatically processed by the receiver (see Globalization).

If you use the tax system "tax_line_amounts" an additional property "amount" is available on the tax object. But the percentage should always be present.

Period

The start and end date this invoice line is for.

Identifications

Three item identifications are available:

buyersItemIdentification
sellersItemIdentification
standardItemIdentification

If you use this identifier, a scheme is also mandatory. It defaults to GTIN (0160).

References

The invoice line id "lineId" can be used to reference this invoice line in other documents. It can be anything, but it is good practice to use an integer. You may run into problems with the receiver otherwise.

It is possible to add a reference to the lineId in the purchase order on which this invoice is based ("orderLineReferenceLineId"). But that purchase order can only be specified at the invoice level. In E-invoicing it is not considerered good practice to send a single invoice for multiple purchase orders. But you obviously can send multiple invoices for a single purchase order.

The accounting cost field helps the receiver book the invoice against the correct general ledger account.

Key/value Pairs

It is possible to add arbitrary key/value pairs to the invoice line. The semantics of these are not defined, but if you have agreed that with your receiver these can be very relevant. Not all invoice formats support this, so they may get dropped. But if they are, that is the responsibility of the receiver who dictates the format.

Allowances and Charges

Allowances and charges are just simplified invoice lines. But tax-wise they share the same complexity. Not all receivers support these, so we advise to be careful using these. If necessary, we will transform them into invoice lines.

Summary Amounts

Only a single document currency can be used for all the amounts in the invoice. So you can not mix-and-match currencies accross invoice lines, specify prices in a different currency, etc. There is, however, one exception: you can specify the total amount of tax in a different currency if that is required for accounting purposes.

How you calculate the tax subtotals depends on the tax system.

tax_line_percentages

First, create a list of unique (country, category, percentage)-keys from all the tax objects in the invoice lines and allowances and charges. Next, for each key, sum the amountsExcludingTax from all the invoice lines in which that key appears. Finally, apply the percentage to that amount to get the tax amount.
tax_line_amounts

For this tax system the calcuation is performed by us.

You must also provide the total payable amount for the invoice. That should be the sum of all the invoice lines + the sum of all the taxes.

3.3.3. JSON Object

Invoice

The following gives the maximum JSON object for an invoice:

Invoice

Invoice Response

The Invoice Response document (DocumentInvoiceResponse,DocumentInvoiceResponse), which you can send after receiving a purchase invoice, is very simple in its most basic form:

InvoiceResponse - basic

The "receiveGuid" property is the guid that you received in the received_invoice webhook. The "AP" response means the document was accepted.

A more complex example is

InvoiceResponse - complete

In this case, the invoice was rejected (RE) with reason "REF" (this means "References incorrect") and no further action on this invoice is expected ("NOA") since it was rejected and the defect cannot be repaired.

Order

The following gives the maximum JSON object for an order:

Order

3.3.4. Webhooks for Sending

Invoice Submission

The invoice_submission is an event specific to the invoice document type, whereas the document_submission is more generic. Support for invoice_submission will be removed in a future release.

When an invoice submission is complete (more specifically all its actions have executed) we make a request to your webhooks in the following format:

{
    "event_type": "invoice_submission",
    "guid": "f4624435-7fc4-4fc2-9379-dcb641d593dc",
    "result": "failed",
    "actions": [{
        "type": "peppol",
        "destination": "NL:VAT.NL012345678B01",
        "result": "error"
    }],
    "tenant_id": "YourTenantId"
}

Possible results are:

succeeded
failed
no_action_taken

The result 'no action taken' is sent when none of the Peppol identifiers were available on the Peppol network and no fallback email address was provided.

There are three types of actions:

peppol
edi
email

Each has the following possible results:

received
error
unknown

The status 'unknown' indicates that the result of the action is not yet known. This status is not actively notified, but if you request the invoice_submission status through our API, you may get this status.

We will normally take only one action, but if the action has failed we may retry and create a second, third etc. action until one succeeds.

An invoice submission is considered "succeeded" if one of its actions has status "received".

Document Submission

A webhook to convey the status for sent documents looks as follows:

{
    "event_type": "document_submission",
    "event_group": "invoice",
    "event": "succeeded",
    "v_delivery": true,
    "details": "A textual representation of the event details, e.g. clarifications for Under Query",
    "response_document": null,
    "guid": "f4624435-7fc4-4fc2-9379-dcb641d593dc",
    "idempotencyGuid": "7305ebe5-9a39-4981-9f98-c64e340f2886",
    "tenant_id": "YourTenantId"
}

The following events and event_groups can be in the webhook:

Event Type	Event Group	Event	Meaning	Triggered By
document_submission	invoice	no_action_taken	No recipients found to send the document to.	Routing problem. Provide a valid destination.
		failed	Could not send the document. This is a final state.	Unrecoverable technical delivery problem.
		cleared	Cleared by the sender’s tax authority. The next step is to send it to the receiver.	A digital signature/QR code was obtained. Note that in some cases (currently KSA, PT) this QR code is generated by Storecove until the tax authority’s portal is ready.
		succeeded	Received by corner 3	Receipt acknowledged by corner 3.
		The events below can only be received if the sender of the invoice advertises the Invoice Response document on the Peppol network (see Legal Entities) or when sending from an Italian LegalEntity.
		acknowledged	Received by corner 4	Receipt acknowledged by corner 4.
		in_process	Processing by corner 4 started
		under_query	Under query by corner 4
		conditionally_accepted	Conditionally accepted by corner 4
		rejected	Rejected by corner 4
		accepted	Accepted by corner 4
		partially_paid	Partially paid by corner 4
		paid	Paid by corner 4
document_submission	invoice_response	no_action_taken	No recipients found to send the document to.	Routing problem. Provide a valid destination.
		failed	Could not send the document. This is a final state.	Unrecoverable technical delivery problem.
		succeeded	Received by corner 3	Receipt acknowledged by corner 3.

Event Type

Event Group

Event

Meaning

Triggered By

document_submission

invoice

no_action_taken

No recipients found to send the document to.

Routing problem. Provide a valid destination.

failed

Could not send the document. This is a final state.

Unrecoverable technical delivery problem.

cleared

Cleared by the sender’s tax authority. The next step is to send it to the receiver.

A digital signature/QR code was obtained. Note that in some cases (currently KSA, PT) this QR code is generated by Storecove until the tax authority’s portal is ready.

succeeded

Received by corner 3

Receipt acknowledged by corner 3.

The events below can only be received if the sender of the invoice advertises the Invoice Response document on the Peppol network (see Legal Entities) or when sending from an Italian LegalEntity.

acknowledged

Received by corner 4

Receipt acknowledged by corner 4.

in_process

Processing by corner 4 started

under_query

Under query by corner 4

conditionally_accepted

Conditionally accepted by corner 4

rejected

Rejected by corner 4

accepted

Accepted by corner 4

partially_paid

Partially paid by corner 4

paid

Paid by corner 4

document_submission

invoice_response

no_action_taken

No recipients found to send the document to.

Routing problem. Provide a valid destination.

failed

Could not send the document. This is a final state.

Unrecoverable technical delivery problem.

succeeded

Received by corner 3

Receipt acknowledged by corner 3.

The "response_document" property is currently only present for

Peppol Invoice Response documents;
SDI (Italy) response documents ("Notifiche"), such as "NS" (Ricevuta di scarto, meaning the invoice was rejected), "MC" (Ricevuta di mancata consegna, meaning the invoice could not be delivered) and "Ricevuta NE/EC02" (the invoice was received but rejected).

Depending on the scenario, this property "response_document" may or may not be present and may have different contents. For an Invoice Response, the contents are defined by

DocumentInvoiceResponse

For SDI, the contents are an array of error messages:

{
  "errors": [
    {
      "code": "00306",
      "description": "1.4.1.2 <CodiceFiscale> non valido : AAAAAA00A00A000A"
    }
  ]
}

The field

{
  "v_delivery": true
}

indicates that the delivery is assumed to have taken place by the local network, such as SDI. It is named after the V-delivery model ([v-flow-explained]). Further webhooks (e.g. Accepted by corner 4) may be sent, but it is also possible that no further webhooks are sent. The presence of this field indicates that there is only clearing evidence and no sending evidence can be retrieved.

3.3.5. Sending Evidence

After you have received a webhook saying the sending was successful, you can retrieve the evidence for that. That includes the exact document that we created for your receiver as well as evidence regarding the exchange. The endpoint for retrieving the evidence can be found on

Get DocumentSubmission Evidence

3.3.6. Globalization

Storecove provides a single and unified API through which you can send and receive documents worldwide, without worrying about the different syntaxes in use in different regions. Simply provide us with the document data and our API automatically ensures that:

The documents we send for you are compliant with legislation in the sender’s country.
The document is routed to the receiver in the way they want.
The document we send can be processed by the receiver. This means the exact document we send will depend on the receiver and/or their country.

In order to do this, we have implemented the following features:

Compliance

In countries where the invoice to be sent requires approval of the local tax authority we ensure this approval is obtained before sending (e.g. India). This approval often takes the form of a (digitally signed) QR code. We can add that QR code to your PDF if applicable. In countries where the invoice to be sent requires a copy to be sent to the local tax authority we ensure this is done (e.g. Hungary).
Routing
- Exchange Network Routing
  
  When a receiver is a member of an exchange network (e.g. OpenPeppol, DBNAlliance) we will automatically route the invoice over that network.
- Tax Authority Routing
  
  In countries where the invoice has to be sent through a mandatory exchange network (e.g. SDI in Italy) we will automatically route the invoice through that network.
- Public Entity Routing
  
  In many countries the government has set up a portal service through which the invoices to the government are to be delivered. Storecove automatically takes care of that (e.g. France, Italy, Portual, Spain, Netherlands, Belgium, Germany)
- Legacy Static Routing
  
  When a receiver is not part of a discoverable exchange network like OpenPeppol or DBNAlliance, but is available on a private network such as Finvoice, SAP Ariba, Basware and others, a static route defining the channel and document format can be provided in the routing element. The receiver may also be on a legacy EDI (typically AS2 with EDIFACT or ANSI X12 810) connection, either directly or through a service provider, however, this is not supported because it requires a receiver-by-receiver setup.
- Email Routing
  
  When a receiver cannot be reached in any other way, an email with an electronic invoice attachment appropriate for that receiver’s country can be sent. For instance for Germany we send ZUGFeRD/XRechnung, for France Factur-X, for the US ANSI X12 810, etc.
Document Generation

Two challenges exist regarding the exact document to be sent.
- Syntax
  
  Inside a single legal territory (EU, US, AU/NZ ("Trans-Tasman") etc.) the format tends to be well-defined. However, that does not mean a single format can be used.
  
  For instance in the EU (mostly through OpenPeppol) Germany has XRechnung in 2 syntaxes (UBL and CII) as well as ZUGFeRD. The Netherlands has SI-1.2, NLCIUS as well as Peppol BIS V3 with country rules. Belgium Has vanilla Peppol BIS V3. Sweden, Denmark, Norway and Greece all use the Peppol BIS V3 format, but with country rules. For now, only a single UBL syntax exists in AU/NZ, but that is a recent addition and versions are bound to emerge. In the US, the DBNAlliance has defined a UBL-based format. However, ANSI X12 810 is wide-spread.
- Contents
  
  An additional challenge arises when sending between these legal territories. Because of differences in tax systems and payment methods, not each invoice can be generated in each format. Therefore, a sender would need to be aware of these complexities and adjust the document to be sent accordingly. To alleviate these difficulties, we perform two conversions on the invoice to be sent:
  - Tax Conversion
    
    Suppose you want to send invoice from AU to an EU country. In the AU, GST is used. So even if you create a sales invoice with 0% GST, this is still not something that can be used to generate a valid EU format invoice, which requires 0% VAT. We take care of this by automatically recognizing when you export an item from one legal territory to another, applying 0% tax, we will take care of generating a document that has 0% in such a way that the receiver’s format can be generated. If you have to charge a non-zero percentage this is not a problem. For AU, simply provide a 10% AU GST tax percentage and it will be converted to an additinal invoice line. Try it, it will work!
    
    A second issue with tax is rounding. A more detailed discussion of that can be found under Tax System, but in short most receivers in the world expect the tax to be calculated and rounded at the invoice level, but some countries allow the tax to be calculated and rounded at the line level. In the latter model the line taxes do not add up to a perfect percentage of the invoice total and a valid invoice in the receiver’s format can not be created. We solve this by adding one or more rounding invoice lines that do not change the invoice total.
  - Payment Method Conversion
    
    For payment methods, an equally complex situation exists. For instance, an AU sender may use Post Billpay as a payment mean, but that is not understood in the EU and most EU formats do not allow it. So we automatically convert this to an equivalent payment method that is valid in the EU, in this case a credit transfer.
Because of these complexities our service includes the generation of the document to be sent. The Sending Evidence endpoint is then used to retrieve the exact document sent to store for compliancy reasons.

3.3.7. Advanced Routing

In many cases, the routing identifier is the same as one of the receiver’s business identifiers. Some examples:

Country	X2Y	Network	Receiver Business Identifiers	Routing
			Legal Identifier	Tax Identifier	Routing Identifier(s)
DE	B2B	Peppol	DE:VAT	DE:VAT	DE:VAT, fallback to email
DE	B2G	Peppol	DE:LWID		DE:LWID
FI	B2B	Peppol	FI:OVT	FI:VAT	FI:OVT, fallback to email
NL	B2B	Peppol	NL:KVK	NL:VAT	NL:KVK, NL:VAT, fallback to email
NL	B2G	Peppol	NL:OINO		NL:OINO
US	B2B	DBNAlliance	DUNS, GLN, LEI	US:EIN, US:SSN	DUNS, GLN, LEI, US:EIN, US:SSN, fallback to email

Country

X2Y

Network

Receiver Business Identifiers

Routing

Legal Identifier

Tax Identifier

Routing Identifier(s)

B2B

Peppol

DE:VAT

DE:VAT, fallback to email

B2G

Peppol

DE:LWID

B2B

Peppol

FI:OVT

FI:VAT

FI:OVT, fallback to email

B2B

Peppol

NL:KVK

NL:VAT

NL:KVK, NL:VAT, fallback to email

B2G

Peppol

NL:OINO

B2B

DBNAlliance

DUNS, GLN, LEI

US:EIN, US:SSN

DUNS, GLN, LEI, US:EIN, US:SSN, fallback to email

There are a few special-routing-needs countries/networks:

Country	X2Y	Network	Receiver Business Identifiers	Routing
			Legal Identifier	Tax Identifier	Routing Identifier(s)
ES	B2B	FACeB2B		ES:VAT	ES:DIRE
ES	B2G	FACe		ES:VAT	ES:FACE
FI	B2B	Finvoice	FI:OVT	FI:VAT	FI:OPID
SE	B2B	Svefaktura	SE:ORGNR	SE:VAT	SE:OPID (optional)
IT	B2B	SDI		IT:IVA or IT:CF	IT:CUUO
IT	B2G	SDI		IT:IVA	IT:CUUO

Country

X2Y

Network

Receiver Business Identifiers

Routing

Legal Identifier

Tax Identifier

Routing Identifier(s)

B2B

FACeB2B

ES:VAT

ES:DIRE

B2G

FACe

ES:VAT

ES:FACE

B2B

Finvoice

FI:OVT

FI:VAT

FI:OPID

B2B

Svefaktura

SE:ORGNR

SE:VAT

SE:OPID (optional)

B2B

SDI

IT:IVA or IT:CF

IT:CUUO

B2G

SDI

IT:IVA

IT:CUUO

For these, the receiver needs to give the sender their routing identifier or one of their routing identifiers in case the have more than one. Therefore, these connections are setup one-by-one and lack the scalability of exchange networks suchs as Peppol and DBNAlliance.

When agreed between the sender and receiver, it is also possible to use special routing identifiers, even where this is not required. For this purpose a GLN number is often used. For instance:

Country	X2Y	Network	Receiver Business Identifiers	Routing
			Legal Identifier	Tax Identifier	Advanced Routing Identifier
DE	B2B	Peppol	DE:VAT	DE:VAT	GLN
NL	B2B	Peppol	NL:KVK	NL:VAT	GLN

Country

X2Y

Network

Receiver Business Identifiers

Routing

Legal Identifier

Tax Identifier

Advanced Routing Identifier

B2B

Peppol

DE:VAT

GLN

B2B

Peppol

NL:KVK

NL:VAT

GLN

In these cases too, the connections are setup one-by-one and cannot benefit from the scalability of exchange networks suchs as Peppol and DBNAlliance. In some rare cases, documents need to make multiple hops via multiple service providers and in that case this makes sense. But we recommend avoiding this unless absolutely necessary.

3.3.8. PDF Stamping

For PDF stamping, include the following markers in the PDF:

These will be replace by the actual data:

3.4. Receiving Documents

3.4.1. Receiving Flows

There are two ways to process incoming documents:

You are advertising identifiers for a LegalEntity on an exchange network (Peppol, DBNAlliance, etc) and someone sends a document to one of your LegalEntities. This will immediately trigger the Received Document Webhook.
You have received a document through another channel (for instance email) and you would like Storecove to process it. To do this, simply push that document into the

ReceivedDocuments

endpoint. This endpoint currently supports RFC822 emails. So when you have received an email for one of you customers that contains a purchase invoice, you can use this endpoint to process it. If the email contains a valid electronic invoice attachment (including those inside PDFs like ZUGFeRD/Factur-X) it will be processed. You will then receive a Received Document Webhook through which you can retrieve the processed purchase invoice in JSON format.

3.4.2. Received Document Webhook

When a new document has been received for you via an Exchange network, we will send a webhook with the following contents:

{
  "event_type": "received_document",
  "event_group": "invoice",
  "event": "received",
  "document_guid": "f4624435-7fc4-4fc2-9379-dcb641d593dc",
  "processing_notes": [],
  "tenant_id": "YourTenantId"
}

If you have POSTed a received document into the ReceivedDocuments endpoint, the webhook will also have a "receive_guid" property:

{
  "event_type": "received_document",
  "event_group": "invoice",
  "event": "received",
  "receive_guid": "d9d395f8-771d-4b93-b0a5-11e9a7d7d6f5",
  "document_guid": "f4624435-7fc4-4fc2-9379-dcb641d593dc",
  "processing_notes": [],
  "tenant_id": "YourTenantId"
}

The "receive_guid" is the same guid you received when POSTing the document to the ReceivedDocuments endpoint. You can use this to correlate the webhook with the POSTed document.

The deprecated "received_invoice" looks as follows:

{
    "event_type": "received_invoice",
    "guid": "f4624435-7fc4-4fc2-9379-dcb641d593dc",
    "tenant_id": "YourTenantId"
}

You can then use the "document_guid" to retrieve the document from the following endpoint:

Get a new ReceivedDocument

{
  "event_type": "received_document",
  "event_group": "unknown",
  "event": "failed",
  "receive_guid": "d9d395f8-771d-4b93-b0a5-11e9a7d7d6f5",
  "document_guid": null,
  "processing_notes": [
    {
      "noted_at": "2023-10-18 10:24:08+00:00",
      "note": "Processing started"
    },
    {
      "noted_at": "2023-10-18 10:24:08+00:00",
      "note": "Invalid data attachment: [TaxTotal][TaxAmount] must equal the sum of the [TaxTotal][TaxSubtotal], but calculated 6.3 != 9999.3"
    }
  ],
  "tenant_id": "YourTenantId"
}

Event Type	Event Group	Event	Meaning
received_document	invoice	received	A new document was received.
	unknown	failed	Could not process the document

Event Type

Event Group

Event

Meaning

received_document

invoice

received

A new document was received.

unknown

failed

Could not process the document

3.4.3. Document Formats

The endpoint supports two formats. In particular:

JSON

The document that we have received is parsed into a JSON object. This means you don’t need to worry about the format the actual document was exchanged in: the JSON always has the same structure. This makes receiving easy to implement, without having to worry about the format-zoo out there.
Original

Although the JSON is easy to process, for compliance reaons you may also want to store the document as it was actually exchanged. That is also possible through this endpoint. Note this is only possible for documents received via an Exchange Network.

3.4.4. JSON Object Invoice

An example JSON object for a purchase invoice with all possible fields is:

{
  "guid": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "legal_entity_id": 9999999,
  "system_generated_primary_image": true,
  "document_type": "invoice",
  "sub_type": "invoice",
  "source": "peppol",
  "tax_system": "tax_line_percentages",
  "invoice_number": "201902088624",
  "issue_date": "2019-03-01",
  "tax_point_date": "2019-03-01",
  "due_date": null,
  "document_currency_code": "EUR",
  "period_start": "2021-12-01",
  "period_end": "2021-12-31",
  "note": "The invoice note. If multiple notes were received these will be concatenated.",
  "accounting_cost": "accounting cost or accounting cost code",
  "attachments": [
    {
      "document": "<base64 encoded document snip>",
      "content_type": "application/pdf",
      "primary_image": true
    }
  ],
  "sender": {
    "party_name": "Demo company",
    "legal_name": "Demo company",
    "department": null,
    "line1": "Address 1",
    "line2": null,
    "zip": "Zippy",
    "city": "Cityname",
	"building_number": "2929",
 	"secondary_number": "8181",
	"neighborhood": "حي العارض",
    "county": null,
    "country": "NL",
    "billing_contact": {
      "first_name": null,
      "last_name": null,
      "email": "info@example.com",
      "phone": "0123456789"
    },
    "identifiers": [
      {
        "superscheme": "iso6523-actorid-upis",
        "scheme": "NL:KVK",
        "scheme_numeric": "0106",
        "identifier": "999999999"
      }
	]
  },
  "payment_terms_note": "Note on the payment",
  "payment_means_array": [
    {
      "type": "CreditTransferPaymentMean",
      "account": "",
      "branche_code": "",
      "mandate": "",
      "network": ""
    }
  ],
  "delivery": {
    "actual_date": "2021-12-31",
    "party": {
      "name": "Receiving party"
    },
    "location": {
      "id": "",
      "scheme_id": "",
      "department": "",
      "line1": "",
      "line2": "",
      "zip": "",
      "city": "",
      "building_number": "2929",
 	  "secondary_number": "8181",
	  "neighborhood": "حي العارض",
      "county": "",
      "country": ""
    }
  },
  "invoice_lines": [
    {
      "name": "This invoice line",
      "description": "A description of this invoice line",
      "period_start": "2021-12-01",
      "period_end": "2021-12-31",
      "allowance_charges": [
        {
          "amount": 0.00,
          "reason": "extra discount"
        }
      ],
      "price": {
        "amount": 10.25,
        "base_quantity": 1.0
      },
      "units": {
        "quantity": 1.0,
        "unit_code": "C62"
      },
      "amount_excluding_tax": 10.25,
      "tax": {
        "tax_amount": 0.00,
        "percentage": 0.00,
        "country": "US",
        "category": "standard",
        "type": "VAT"
      },
      "accounting": {
        "code": "code",
        "name": "code description",
        "list": "list of the code",
        "list_version": "list_version"
      },
      "note": "This is a note for this invoice line"
    }
  ],
  "allowance_charges": [
    {
      "amount_excluding_tax": 0.00,
      "tax": {
        "tax_amount": 0.00,
        "percentage": 0.00,
        "country": "US",
        "category": "standard",
        "type": "VAT"
      },
      "reason": ""
    }
  ],
  "document_totals": {
    "total": 12.40,
    "rounding": 0.00,
    "prepaid": 0.00,
    "payable": 12.40,
  },
  "accounting_currency_taxable_amount": 0.00,
  "accounting_currency_tax_amount": 0.00,
  "accounting_currency_exchange_rate": 1.00,
  "tax_subtotals": [
    {
      "amount_excluding_tax": 0.00,
      "tax": {
        "tax_amount": 0.00,
        "percentage": 0.00,
        "country": "US",
        "category": "standard",
        "type": "VAT"
      }
    }
  ]
}

Change Log

The baseline version of the purchase invoice JSON object is 2024-01-01. If you specify a version before that or no version at all, you will get a JSON that includes deprecated features.

The following changes have been made since the baseline version:

2024-01-01

Baseline version

2024-03-01

add missing attachment.filename property
deprecate attachment.content_type in favor of attachment.mime_type
wrap company_name, registration_name, address and contact in a party object
fix party addresses
reference object: include null-valued properties too
tax_subtotals objects now conform to documentation (TaxSubtotal)

2024-05-01

invoice lines and allowance_charge objects now contain an array of taxes_duties_fees objects, no longer a single tax object.
added missing document line note field. This field is also added for all older versions.

2024-06-01

invoices now contain
- accounting_currency_tax_amount
- accounting_currency_tax_base_amount
- accounting_currency_exchange_rate

3.4.5. JSON Object Order

The baseline version of the received order JSON object is 2024-01-01. If you specify a version before that or no version at all, you will get a JSON that includes deprecated features.

Since version 2024-03-01 the JSON object for a received order is the same as for a sent order, so for a complete example see Order.

The following changes have been made since the baseline version:

2024-01-01

Baseline version

2024-03-01

add missing attachment.filename property
deprecate attachment.content_type in favor of attachment.mime_type
wrap company_name, registration_name, address and contact in a party object
fix party addresses
reference object: include null-valued properties too
tax_subtotals objects now conform to documentation (TaxSubtotal)
don’t include the sellerSupplierParty since it is represented by the legal_entity_id
fix requested_delivery_period to use a '-' not a '=' to separate the start and end dates
delivery.shipping_marks is a string, not an array
rename order_line.price to order_line.item_price
order_line.taxes_duties_fees.percentage is now always a number, not sometimes a string
add missing orderline.delivery.delivery_location

4. Various Deprecated

4.1. Reporting

If you use the API then you will receive feedback on the status of documents via webhooks. But if you use legacy connection types such as SFTP or SMTP, that is not possible. For those cases we can setup a daily report via email with the result of all yesterday’s documents sent.

This report contains a column "action required" that you can use to filter only those documents that require action to be taken. The subject of the email will also be prefixed with "OK" or "ACTION REQUIRED" depending on the contents of the report.

This report is often sent directly to the customer service department, where the failed documents can be investigated and fixed. For instance, for first-time revenue, often the email address was not entered correctly. Handling this proactively can save signifact cost downstream in the collections process.

Sending Sales Invoices

For companies wishing to send sales invoices to their Customers through various channels, including the Peppol network (becoming mandatory in the EU for all public entities), our service sends your invoices as e-invoices that can be automatically processed by your Customer’s accountancy software package / ERP.

There are two ways of presenting your sales invoices into the Storecove platform for e-delivery:

By emailing your sales invoices to <your_company_name>@send.storecove.com
By uploading your sales invoices via SFTP to <your_company_name>@sftp.storecove.com
By pushing your sales invoices into our API

We have a web interface where you can view how we processed your invoice and take action on any errors.

If you use our API, the added benefit is that you can configure Webhooks that we will call, updating you with the delivery status of your sales invoice. In addition, you can integrate the delivery status of sales invoices in your customer service environment by requesting their status.

Please see [Individual Companies] for details.

Receiving Purchase Invoices

For receiving invoices there are two solutions that we offer:

The Peppol European e-invoicing network
<your_company_name>@receive.storecove.com (with optional scan&recognize)

Both will give you not only the PDF invoice, but also the e-invoice, ready for automated processing in your ERP without any manual intervention.

These services can be fully managed via the web interface and no API integration is necessary.

We can deliver purchase invoices to most accountancy software packages, either through their API or by sending the purchase invoice to an email address. It is also possible to leverage our Webhooks, which allow you to configure a URL that we will call each time a purchase invoice is received. You can then retrieve it and process it in your ERP.

Sending Sales Invoices

There are two ways of presenting your sales invoices into the Storecove platform for e-delivery:

By emailing your sales invoices to <your_company_name>@send.storecove.com
By uploading your sales invoices via SFTP to <your_company_name>@sftp.storecove.com
By pushing your sales invoices into our API

We have a web interface where you can view how we processed your invoice and take action on any errors.

Please see [Individual Companies] for details.

Receiving Purchase Invoices

For receiving invoices there are two solutions that we offer:

The Peppol European e-invoicing network
<your_company_name>@receive.storecove.com (with optional scan&recognize)

Both will give you not only the PDF invoice, but also the e-invoice, ready for automated processing in your ERP without any manual intervention.

These services can be fully managed via the web interface and no API integration is necessary.

4.2. Email Ingestion

4.2.1. Introduction

Email ingestion refers to Storecove receiving and processing your (or your Client’s) invoice via an email to <company_name>@send.storecove.com. This email should have an attachment that contains the data that makes up the invoice and optionally an attachment that has an image of the invoice, in PDF format.

4.2.2. From: Address

The address you send from determines your identity as sender of the invoice, and so therefore needs to be validated by Storecove. The entire process is described on

https://help.storecove.com/verzenden-en-ontvangen-via-peppol/facturen-verzenden-via-peppol

4.2.3. To: Address

If you have followed the previous link, you will have setup an email addresss <company_name>@send.storecove.com. You can send emails to this address with your electronic invoices to send.

4.2.4. Attachments

Data

You need to provide an attachment with the data contained in the invoice.

You can attach a UBL 2.0 or UBL 2.1 invoice. Even if these are not 100% compliant, we can probably process them. Contact us on helpdesk@storecove.com for a test if you are not sure.

If you cannot produce a UBL attachment, we also support other formats (like CII, SAP IDoc, cXML, CSV) and we can also support your custom format. Contact us on helpdesk@storecove.com if you need to use a non-UBL format.

PDF

If you have a PDF image of the invoice, you can provide it as an attachment. This attachment’s filename should end in ‘.pdf’. If you do not have a PDF to attach, just leave it out and we will create one for you

4.3. SFTP Ingestion

4.3.1. Introduction

SFTP ingestion refers to Storecove receiving and processing your (or your Client’s) invoices via secure file upload to <company_name>@sftp.storecove.com.

4.3.2. Files

The upload may consist of mulitple files, each with its own purpose. We currently support the following purposes:

Data
Primary image
Additional attachments

The data file contains the data of the invoice. It usually is in UBL format, but if you cannot produce a UBL file, we also support other formats (like CII, SAP Ioc, cXML, CSV) and we can also support your custom format. Contact us if you need to use a non-UBL format. The primary image file should be a PDF. The additional attachments are currently also limited to PDF only, but please contact us if you have different requirements.

The filenames, always in lowecase, have the following structure:

<file_id>_<purpose>.<extension> or
<file_id>_<purpose>_<participant_identifier>.<extension> or
<file_id>_additional_<counter>.<extension> or
<file_id>_additional_<counter>_<participant_identifier>.<extension>

All files pertaining to the same invoice should have the same file_id. The file_id should never be re-used. The file_id must be a uuid (any version) and therefore may contain only the following characters:

a-f, 0-9 and '-'

and have the following structure:

cccccccc-cccc-cccc-cccc-cccccccccccc

Note that if you use a hash of the invoice number as file_id, that may work, but you will not be able to resend that invoice. For that reason, it is recommended to include a random string to make the file_id globally unique.

The purpose must be one of:

data (this file contains the invoice data and may occur only once)
primary (this is the primary image of the invoice, i.e. a PDF of the invoice. It may occur only once.)
additional (this indicates an additional attachment, perhaps an invoice specification. It may occur multiple times)
structure (see below)

Examples of valid file names are:

82b3785e-0569-482d-a683-ee437eb3df13_data.xml
82b3785e-0569-482d-a683-ee437eb3df13_primary.pdf
82b3785e-0569-482d-a683-ee437eb3df13_additional_1.pdf
82b3785e-0569-482d-a683-ee437eb3df13_primary_nl-oin.00000000000000000000.pdf
82b3785e-0569-482d-a683-ee437eb3df13_additional_hr-vat.hr12345678901_1.pdf
82b3785e-0569-482d-a683-ee437eb3df13_primary_0190.00000000000000000000.pdf
82b3785e-0569-482d-a683-ee437eb3df13_additional_9934.hr12345678901_1.pdf

It is best to provide your participant identifiers in the data file. That way, you can provide as many as you have. If you are not able to include the participant identifiers in the data file, the filename is the next best option. It can, however, hold only a single participant identifier. The full list of participant identifiers can be found here: Receiver Identifiers

4.3.3. Structure

If you always provide the same set of files (for instance: only a data file or only a data file + a PDF file) then we will configure this statically when we setup your SFTP upload capability. If, however, you wish to have the ability to provide different sets of documents (for instance: sometimes you provide one or more additional attachments, but sometimes you don’t) then it is possible to send us structure of your invoice submission through a separate file, the structure file. It contains a description of which files make up the invoice submission and so we will wait processing the already uploaded files until the set is complete. The contents of the structure file looks like this:

{
    "documents": [
        {
            "purpose": "data",
            "extension": "xml",
            "count": 1
        },
        {
            "purpose": "primary",
            "extension": "pdf",
            "count": 1
        },
        {
            "purpose": "additional",
            "extension": "pdf",
            "count": 2
        }
    ]
}

You have to choose: either you always provide the same set of files, or you always provide a structure file.

4.3.4. Setup

At this moment the setup cannot be done through our web interface. Therefore, please contact us on helpdesk@storecove.com to setup your SFTP upload capability.

4.3.5. Key pair

To setup SFTP, we you need to generate an SSH keypair and send us the public part. On Linux:

ssh-keygen -t rsa -b 4096 -f id_rsa

Leave the passwords empty. Send us the file

id_rsa.pub

Don’t send us your id_rsa file, that is to be kept private.

4.4. Access Point as-a Service

Software suppliers use Storecove as a Peppol Access Point to provide e-invoicing to their customers. For example, if you are an e-commerce SaaS product, Storecove would provide your e-invoicing functionality to many client businesses.

You can use Storecove for your own e-invoicing (as a a company), and for your clients (Access Point as a Service).

4.5. Introduction

Use the API calls

Create a new LegalEntity Create a new PeppolIdentifier

to mange your organizations and their peppol identifiers.

4.6. Sending

For sending, you may want to first "preflight"

DEPRECATED. Preflight an invoice recipient

to check whether a Peppol identifier can be reached on the Peppol network. Next, send your invoice using

DEPRECATED. Submit a new invoice

If you send all your invoices through Storecove (i.e. to an email if we cannot send it via Peppol) you do not need to preflight.

4.7. Receiving

Configure the appropriate webhook. See Webhooks.

4.8. Embedded Supplier Connections

4.8.1. Introduction

This API facilitates white label embedding Storecove Script Connections into your own service/product. This enables your users to manage the credentials with which Storecove retrieves invoices from suppliers, directly in your website.

4.8.2. Use

The typical use-case is as follows:

You show your user a list of suppliers to choose from.
When they click on a supplier, they provide their username/password in a modal form.
When they save, you create a ShopAccount via the Storecove API

You should not limit the list of suppliers to only suppliers the user does not yet have connected, since it is possible to have more than one connection to the same supplier (e.g. two mobile phone subscriptions with Vodafone with separate accounts).

The list of available suppliers can be found with this API call:

[_openapi_shops_index]

When a user connects a new supplier, you create a new ShopAccount with the following API call:

[_openapi_create_shop_account]

When a new invoice is retrieved, you are notified via a webhook (Webhooks).

Invoices will be retrieved from one month before the moment on which the ShopAccount was created.

Authorization failures

If your user provides the wrong credentials, the connection with the supplier cannot be created and invoices are not retrieved. The user needs to take action. A call is available to receive a list of ShopAccounts that have been diagnosed with an authorization problem:

The following are the relevant fields in each ShopAccount: id, external_user_id, sign_in_error_confirmed, sign_in_error_confirmed_at. Poll daily and process the result:

If a ShopAccount is on your list, but no longer in the list returned, then either the problem was resolved or it was not resolved for too many days and the ShopAccount has therefore been dropped by Storecove (currently after 30 days). In both cases, remove the id from your list. To determine what happened, request the ShopAccount by its id. You will receive a 200 or a 404.
If a ShopAccount is not yet on your list, add it. You can now start the process that you want to follow to alert the user. For instance, you could email them and/or show the problem in your web interface.
When someone changes their credentials in your web interface, remove the id from your list immediately after updating the ShopAccount via the API.

5. Best Practices

5.1. Job Queues

The Storecove API is highly available. However, that does not mean 100%.

We therefore recommend that all POSTs to our API are done in a job queue. Jobs can be rescheduled to automatically retry after an (increasing) amount of time and should the job finally fail, you can investigate why and potentially reschedule it manually. Typically, whenever you receive an HTTP response 500-599 (indicating a server-side error) you can retry, when you receive a response 400-499 (indicating a client side error) you need to investigate.

5.2. Production Data

It is highly recommended to use (optionally anonimized) real production data during development. Our experience is that if you make up your own invoice data, you are going to run into error message after error message, making the whole process very frustrating. Invoices are complex objects and using production data ensures your data is consistent and relevant.

5.3. Resilience to Changes

It is our policy to not introduce breaking changes in our API except with a major version upgrade. The last major version upgrade was over five years ago and the next one is not on the cards. That means once you have completed your integration, you do not need to worry about Storecove forcing you into a continouous stream of maintenance changes.

However, we do make backwards compatible changes to our API nearly every day. The following are changes that we consider to be backwards compatible:

Adding new API resources
Adding new methods for a resource
Adding new attributes to existing API responses
Changing the order of attributes in existing API responses
Adding new input attributes to existing API methods
Adding new event types, event groups and events

In order for your code to be resilient to these types of backwards compatible changes, we recommend the following best practices:

Ignore response attributes that you don’t recognize You can do this as follows in popular environments:

Java (Jackson):

@JsonIgnoreProperties(ignoreUnknown = true)

.NET (System.Text.Json .NET Core 3.0+):

var options = new JsonSerializerOptions
{
    IgnoreUnknownJsonFields = true // This option directly tells the serializer to ignore unknown fields
};
var myObject = JsonSerializer.Deserialize<MyObjectType>(jsonString, options);

.NET (Newtonsoft.Json):

var settings = new JsonSerializerSettings
{
    MissingMemberHandling = MissingMemberHandling.Ignore // Ignore properties during deserialization that are not found in the target type
};
var myObject = JsonConvert.DeserializeObject<MyObjectType>(jsonString, settings);

Ignore event types, event groups and events that you don’t recognize

Also, from time to time, we may introduce enhanced validation rules that prevent illegal scenarios from occurring. This should not lead to problems in your production environment, but in development, if you are not using valid production scenario’s, you may encounter invalid scenario’s being blocked. This is why we recommend using (anonymized) production data for development and test.

6. API Reference

6.1. Resources

6.1.1. AdditionalTaxIdentifiers

Create a new AdditionalTaxIdentifier

POST /legal_entities/{legal_entity_id}/additional_tax_identifiers

Description

Create a new AdditionalTaxIdentifier. An AdditionalTaxIdentifier is a seconday tax identifier that is used inside the EU when sending invoices to consumers. In that case, the VAT of the receiving country is used and if the sender has a local VAT identifier, that is used to identifiy the sender, instead of the sender’s origin country VAT number. To use these identifiers, use the invoice.consumerTaxMode = true property.

Parameters

Type	Name	Description	Schema
Path	legal_entity_id required	The id of the LegalEntity for which to create the AdditionalTaxIdentifier	integer (int64)
Body	additional_tax_identifier required	AdditionalTaxIdentifier to create	AdditionalTaxIdentifierCreate

Type

Name

Description

Schema

Path

legal_entity_id
required

The id of the LegalEntity for which to create the AdditionalTaxIdentifier

integer (int64)

Body

additional_tax_identifier
required

AdditionalTaxIdentifier to create

AdditionalTaxIdentifierCreate

Responses

HTTP Code	Description	Schema
200	Success	AdditionalTaxIdentifier
401	Unauthorized	No Content
403	Forbidden	No Content
404	Not Found	No Content
422	Unprocessable Entity	< ErrorModel > array

HTTP Code

Description

Schema

200

Success

AdditionalTaxIdentifier

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

422

Unprocessable Entity

< ErrorModel > array

Consumes

application/json

Get AdditionalTaxIdentifier

GET /legal_entities/{legal_entity_id}/additional_tax_identifiers/{id}

Description

Get an AdditionalTaxIdentifier

Parameters

Type	Name	Description	Schema
Path	id required	The id of the AdditionalTaxIdentifier	integer (int64)
Path	legal_entity_id required	The id of the LegalEntity the AdditionalTaxIdentifier belongs to	integer (int64)

Type

Name

Description

Schema

Path

id
required

The id of the AdditionalTaxIdentifier

integer (int64)

Path

legal_entity_id
required

The id of the LegalEntity the AdditionalTaxIdentifier belongs to

integer (int64)

Responses

HTTP Code	Description	Schema
200	Success	AdditionalTaxIdentifier
401	Unauthorized	No Content
403	Forbidden	No Content
404	Not Found	No Content

HTTP Code

Description

Schema

200

Success

AdditionalTaxIdentifier

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

Delete AdditionalTaxIdentifier

DELETE /legal_entities/{legal_entity_id}/additional_tax_identifiers/{id}

Description

Delete an AdditionalTaxIdentifier

Parameters

Type	Name	Description	Schema
Path	id required	The id of the AdditionalTaxIdentifier	integer (int64)
Path	legal_entity_id required	The id of the LegalEntity the AdditionalTaxIdentifier belongs to	integer (int64)

Type

Name

Description

Schema

Path

id
required

The id of the AdditionalTaxIdentifier

integer (int64)

Path

legal_entity_id
required

The id of the LegalEntity the AdditionalTaxIdentifier belongs to

integer (int64)

Responses

HTTP Code	Description	Schema
204	Success	No Content
401	Unauthorized	No Content
403	Forbidden	No Content
404	Not Found	No Content

HTTP Code

Description

Schema

204

Success

No Content

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

Update AdditionalTaxIdentifier

PATCH /legal_entities/{legal_entity_id}/additional_tax_identifiers/{id}

Description

Update an AdditionalTaxIdentifier

Parameters

Type	Name	Description	Schema
Path	id required	The id of the AdditionalTaxIdentifier to be updated	integer (int64)
Path	legal_entity_id required	The id of the LegalEntity the AdditionalTaxIdentifier belongs to	integer (int64)
Body	additional_tax_identifier required	AdditionalTaxIdentifier to update	AdditionalTaxIdentifierUpdate

Type

Name

Description

Schema

Path

id
required

The id of the AdditionalTaxIdentifier to be updated

integer (int64)

Path

legal_entity_id
required

The id of the LegalEntity the AdditionalTaxIdentifier belongs to

integer (int64)

Body

additional_tax_identifier
required

AdditionalTaxIdentifier to update

AdditionalTaxIdentifierUpdate

Responses

HTTP Code	Description	Schema
200	Success	AdditionalTaxIdentifier
401	Unauthorized	No Content
403	Forbidden	No Content
404	Not Found	No Content

HTTP Code

Description

Schema

200

Success

AdditionalTaxIdentifier

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

6.1.2. Administrations

DEPRECATED. Create a new Administration

POST /legal_entities/{legal_entity_id}/administrations

Description

DEPRECATED. Create a new Administration. An Administration is an email destination for purchase invoices.

Parameters

Type	Name	Description	Schema
Path	legal_entity_id required	The id of the LegalEntity for which to create the Administration	integer (int64)
Body	administration required	Administration to create	AdministrationCreate

Type

Name

Description

Schema

Path

legal_entity_id
required

The id of the LegalEntity for which to create the Administration

integer (int64)

Body

administration
required

Administration to create

AdministrationCreate

Responses

HTTP Code	Description	Schema
200	Success	Administration
401	Unauthorized	No Content
403	Forbidden	No Content
404	Not Found	No Content
422	Unprocessable Entity	< ErrorModel > array

HTTP Code

Description

Schema

200

Success

Administration

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

422

Unprocessable Entity

< ErrorModel > array

Consumes

application/json

DEPRECATED. Get Administration

GET /legal_entities/{legal_entity_id}/administrations/{id}

Description

DEPRECATED. Get an Administration

Parameters

Type	Name	Description	Schema
Path	id required	The id of the Administration	integer (int64)
Path	legal_entity_id required	The id of the LegalEntity the Administration belongs to	integer (int64)

Type

Name

Description

Schema

Path

id
required

The id of the Administration

integer (int64)

Path

legal_entity_id
required

The id of the LegalEntity the Administration belongs to

integer (int64)

Responses

HTTP Code	Description	Schema
200	Success	Administration
401	Unauthorized	No Content
403	Forbidden	No Content
404	Not Found	No Content

HTTP Code

Description

Schema

200

Success

Administration

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

DEPRECATED. Delete Administration

DELETE /legal_entities/{legal_entity_id}/administrations/{id}

Description

DEPRECATED. Delete an Administration

Parameters

Type	Name	Description	Schema
Path	id required	The id of the Administration	integer (int64)
Path	legal_entity_id required	The id of the LegalEntity the Administration belongs to	integer (int64)

Type

Name

Description

Schema

Path

id
required

The id of the Administration

integer (int64)

Path

legal_entity_id
required

The id of the LegalEntity the Administration belongs to

integer (int64)

Responses

HTTP Code	Description	Schema
204	Success	No Content
401	Unauthorized	No Content
403	Forbidden	No Content
404	Not Found	No Content

HTTP Code

Description

Schema

204

Success

No Content

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

DEPRECATED. Update Administration

PATCH /legal_entities/{legal_entity_id}/administrations/{id}

Description

DEPRECATED. Update an Administration

Parameters

Type	Name	Description	Schema
Path	id required	The id of the Administration to be updated	integer (int64)
Path	legal_entity_id required	The id of the LegalEntity the Administration belongs to	integer (int64)
Body	administration required	Administration to update	AdministrationUpdate

Type

Name

Description

Schema

Path

id
required

The id of the Administration to be updated

integer (int64)

Path

legal_entity_id
required

The id of the LegalEntity the Administration belongs to

integer (int64)

Body

administration
required

Administration to update

AdministrationUpdate

Responses

HTTP Code	Description	Schema
200	Success	Administration
401	Unauthorized	No Content
403	Forbidden	No Content
404	Not Found	No Content

HTTP Code

Description

Schema

200

Success

Administration

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

6.1.3. C5Activation

6.1.4. Discovery

Discover Network Participant Existence

POST /discovery/exists

Description

Discover if a network participant exists.

Parameters

Type	Name	Description	Schema
Body	discoverable_participant required	The participant to check	DiscoverableParticipant

Type

Name

Description

Schema

Body

discoverable_participant
required

The participant to check

DiscoverableParticipant

Responses

HTTP Code	Description	Schema
200	Success	DiscoveredParticipant
401	Unauthorized	No Content
403	Forbidden	No Content
422	Unprocessable Entity	< ErrorModel > array

HTTP Code

Description

Schema

200

Success

DiscoveredParticipant

401

Unauthorized

No Content

403

Forbidden

No Content

422

Unprocessable Entity

< ErrorModel > array

Consumes

application/json

Discover Country Identifiers ** EXPERIMENTAL

GET /discovery/identifiers

Description

Discover the identifiers used in each country, for routing, for legal identification as well as for tax identification purposes. We are currently testing this endpoint with selected Customers. If you would like to participate, please contact us.

Responses

HTTP Code	Description	Schema
200	Success	CountrySpecifications
401	Unauthorized	No Content
403	Forbidden	No Content

HTTP Code

Description

Schema

200

Success

CountrySpecifications

401

Unauthorized

No Content

403

Forbidden

No Content

Discover Network Participant Capabilites

POST /discovery/receives

Description

Discover a network participant and their capabilities.

Parameters

Type	Name	Description	Schema
Body	discoverable_participant required	The participant to check	DiscoverableParticipant

Type

Name

Description

Schema

Body

discoverable_participant
required

The participant to check

DiscoverableParticipant

Responses

HTTP Code	Description	Schema
200	Success	DiscoveredParticipant
401	Unauthorized	No Content
403	Forbidden	No Content
422	Unprocessable Entity	< ErrorModel > array

HTTP Code

Description

Schema

200

Success

DiscoveredParticipant

401

Unauthorized

No Content

403

Forbidden

No Content

422

Unprocessable Entity

< ErrorModel > array

Consumes

application/json

6.1.5. DocumentSubmissions

Submit a new document.

POST /document_submissions

Description

Submit a document for delivery.

Parameters

Type	Name	Description	Schema
Body	document_submission required	Document to submit	DocumentSubmission

Type

Name

Description

Schema

Body

document_submission
required

Document to submit

DocumentSubmission

Responses

HTTP Code	Description	Schema
200	Success	DocumentSubmissionResult
401	Unauthorized	No Content
403	Forbidden	No Content
422	Unprocessable Entity	< ErrorModel > array

HTTP Code

Description

Schema

200

Success

DocumentSubmissionResult

401

Unauthorized

No Content

403

Forbidden

No Content

422

Unprocessable Entity

< ErrorModel > array

Consumes

application/json

Get DocumentSubmission Evidence

GET /document_submissions/{guid}/evidence/{evidence_type}

Description

Get evidence for a DocumentSubmission by GUID with corresponding status

Parameters

Type Name Description Schema Default

Type	Name	Description	Schema	Default
Path	evidence_type optional	Type of evidence requested	enum (sending, clearing)	`"sending"`
Path	guid required	DocumentSubmission GUID	string (uuid)

Path

evidence_type
optional

Type of evidence requested

enum (sending, clearing)

"sending"

Path

guid
required

DocumentSubmission GUID

string (uuid)

Responses

HTTP Code	Description	Schema
200	Success	DocumentSubmissionEvidence
401	Unauthorized	No Content
403	Forbidden	No Content
404	Not Found	No Content

HTTP Code

Description

Schema

200

Success

DocumentSubmissionEvidence

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

Consumes

application/json

6.1.6. InvoiceSubmissions

DEPRECATED. Submit a new invoice

POST /invoice_submissions

Description

DEPRECATED. Use the new /document_submissions endpoint. Submit an invoice for delivery.

Parameters

Type	Name	Description	Schema
Body	invoice_submission required	Invoice to submit	InvoiceSubmission

Type

Name

Description

Schema

Body

invoice_submission
required

Invoice to submit

InvoiceSubmission

Responses

HTTP Code	Description	Schema
200	Success	InvoiceSubmissionResult
401	Unauthorized	No Content
403	Forbidden	No Content
422	Unprocessable Entity	< ErrorModel > array

HTTP Code

Description

Schema

200

Success

InvoiceSubmissionResult

401

Unauthorized

No Content

403

Forbidden

No Content

422

Unprocessable Entity

< ErrorModel > array

Consumes

application/json

DEPRECATED. Preflight an invoice recipient

POST /invoice_submissions/preflight

Description

Deprecated. Use the new /discovery endpoint. Check whether Storecove can deliver an invoice for a list of ids.

Parameters

Type	Name	Description	Schema
Body	invoice_recipient_preflight required	The invoice recipient to preflight	InvoiceRecipientPreflight

Type

Name

Description

Schema

Body

invoice_recipient_preflight
required

The invoice recipient to preflight

InvoiceRecipientPreflight

Responses

HTTP Code	Description	Schema
200	Success	PreflightInvoiceRecipientResult
401	Unauthorized	No Content
403	Forbidden	No Content
422	Unprocessable Entity	< ErrorModel > array

HTTP Code

Description

Schema

200

Success

PreflightInvoiceRecipientResult

401

Unauthorized

No Content

403

Forbidden

No Content

422

Unprocessable Entity

< ErrorModel > array

Consumes

application/json

DEPRECATED. Get InvoiceSubmission Evidence

GET /invoice_submissions/{guid}/evidence

Description

Deprecated. Use the new /document_submissions/{guid}/evidence endpoint. Get evidence for an InvoiceSubmission by GUID with corresponding status

Parameters

Type	Name	Description	Schema
Path	guid required	InvoiceSubmission GUID	string (uuid)

Type

Name

Description

Schema

Path

guid
required

InvoiceSubmission GUID

string (uuid)

Responses

HTTP Code	Description	Schema
200	Success	InvoiceSubmissionEvidence
401	Unauthorized	No Content
403	Forbidden	No Content
404	Not Found	No Content

HTTP Code

Description

Schema

200

Success

InvoiceSubmissionEvidence

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

Consumes

application/json

6.1.7. LegalEntities

Create a new LegalEntity

POST /legal_entities

Description

Create a new LegalEntity.

Parameters

Type

Name

Description

Schema

Body

legal_entity
required

LegalEntity to create

LegalEntityCreate

Responses

HTTP Code

Description

Schema

200

Success

LegalEntity

401

Unauthorized

No Content

403

Forbidden

No Content

422

Unprocessable Entity

< ErrorModel > array

Consumes

application/json

Get LegalEntity

GET /legal_entities/{id}

Description

Get a specific LegalEntity.

Parameters

Type

Name

Description

Schema

Path

id
required

legal_entity id

integer (int64)

Responses

HTTP Code

Description

Schema

200

Success

LegalEntity

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

Delete LegalEntity

DELETE /legal_entities/{id}

Description

Delete a specific LegalEntity.

Parameters

Type

Name

Description

Schema

Path

id
required

legal_entity id

integer (int64)

Responses

HTTP Code

Description

Schema

204

Success

No Content

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

Update LegalEntity

PATCH /legal_entities/{id}

Description

Update a specific LegalEntity.

Parameters

Type

Name

Description

Schema

Path

id
required

legal_entity id

integer (int64)

Body

legal_entity
required

LegalEntity updates

LegalEntityUpdate

Responses

HTTP Code

Description

Schema

200

Success

LegalEntity

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

422

Unprocessable Entity

< ErrorModel > array

6.1.8. PeppolIdentifiers

Create a new PeppolIdentifier

POST /legal_entities/{legal_entity_id}/peppol_identifiers

Description

Create a brand new new PeppolIdentifier. For SG - Singapore, special rules apply.

Parameters

Type

Name

Description

Schema

Path

legal_entity_id
required

The id of the LegalEntity for which to create the PeppolIdentifier

integer (int64)

Body

peppol_identifier
required

PeppolIdentifier to create

PeppolIdentifierCreate

Responses

HTTP Code

Description

Schema

200

Success

PeppolIdentifier

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

422

Unprocessable Entity

< ErrorModel > array

Consumes

application/json

Delete PeppolIdentifier

DELETE /legal_entities/{legal_entity_id}/peppol_identifiers/{superscheme}/{scheme}/{identifier}

Description

Delete a PeppolIdentifier.

Parameters

Type

Name

Description

Schema

Path

identifier
required

PEPPOL identifier

string

Path

legal_entity_id
required

The id of the LegalEntity this PeppolIdentifier belongs to

integer (int64)

Path

scheme
required

PEPPOL identifier scheme id, e.g. "DE:VAT". For a full list see Receiver Identifiers.

string

Path

superscheme
required

The superscheme of the identifier. Should always be "iso6523-actorid-upis".

string

Responses

HTTP Code

Description

Schema

204

Success

No Content

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

6.1.9. PurchaseInvoices

DEPRECATED. Get Purchase invoice data as JSON

GET /purchase_invoices/{guid}

Description

DEPRECATED. Use the /api/v2/received_documents endpoint. Get a specific PurchaseInvoice, in JSON format.

Parameters

Type Name Description Schema Default

Path

guid
required

The guid of the purchase invoice, from the webhook.

string (uuid)

Query

pmv
optional

DEPRECATED. The PaymentMeans version. The default (and deprecated) version 1.0 will give BankPaymentMean, DirectDebitPaymentMean, CardPaymentMean, NppPaymentMean, SeBankGiroPaymentMean, SePlusGiroPaymentMean, SgCardPaymentMean, SgGiroPaymentMean, SgPaynowPaymentMean.

Version 2.0 deprecates BankPaymentMean (now CreditTransferPaymentMean), CardPaymentMean (now CreditCardPaymentMean), NppPaymentMean (now AunzNppPayidPaymentMean), SeBankGiroPaymentMean (now SeBankgiroPaymentMean – note the lower 'g' in 'bankgiro'). It also adds OnlinePaymentServicePaymentMean, StandingAgreementPaymentMean, AunzNppPaytoPaymentMean, AunzBpayPaymentMean, AunzPostbillpayPaymentMean, AunzUriPaymentMean.

string

"1.0"

Query

version
optional

The JSON content version date. The default is '1970-01-01' meaning you get all deprecated elements since nothing was deprecated before that ;). If you do not want deprecated elements, use a later date. Do not use a dynamic date, because that means when we deprecate elements they will disappear from our responses.

string

"1970-01-01"

Responses

HTTP Code

Description

Schema

200

Success

PurchaseInvoice

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

DEPRECATED. Get Purchase invoice data in a selectable format

GET /purchase_invoices/{guid}/{packaging}

Description

DEPRECATED. Use the /api/v2/received_documents endpoint. Get a specific PurchaseInvoice.

Parameters

Type Name Description Schema Default

Path

guid
required

purchase invoice guid

string (uuid)

Path

packaging
required

How to package the purchase invoice. Note that "ubl" is deprecated.

enum (json, ubl, original)

"json"

Query

pmv
optional

string

"1.0"

Query

version
optional

string

"1970-01-01"

Responses

HTTP Code

Description

Schema

200

Success

PurchaseInvoiceUbl

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

DEPRECATED. Get Purchase invoice data as JSON with a Base64-encoded UBL string in the specified version

GET /purchase_invoices/{guid}/{packaging}/{package_version}

Description

DEPRECATED. Get a specific PurchaseInvoice in UBL format

Parameters

Type Name Description Schema Default

Path

guid
required

purchase invoice guid

string (uuid)

Path

package_version
required

The version of the package.

enum (si11, si12, si20, aunz, sg, jp, en16931, original)

"si11"

Path

packaging
required

How to package the purchase invoice.

enum (ubl)

"ubl"

Responses

HTTP Code

Description

Schema

200

Success

PurchaseInvoiceUbl

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

6.1.10. ReceivedDocuments

Receive a new Document

POST /legal_entities/{legal_entity_id}/received_documents

Description

Let us know about a new Document you have received. It will be parsed and then you will receive the "received_document" webhook. You can use the information in the webhook to retrieve the parsed JSON or the original through a GET request.

Parameters

Type

Name

Description

Schema

Path

legal_entity_id
required

The id of the LegalEntity for which the document was received.

integer (int64)

Body

received_document
required

Received document to process.

ReceivedDocumentCreate

Responses

HTTP Code

Description

Schema

200

Success

ReceivedDocument

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

422

Unprocessable Entity

< ErrorModel > array

Consumes

application/json

Get a new ReceivedDocument

GET /received_documents/{guid}/{format}

Description

Get a new ReceivedDocument that you have been notified for via received_document webhook.

Parameters

Type Name Description Schema Default

Path

guid
required

The guid of the document that was received. This is the "document_guid" property of the "received_document" webhook.

string (uuid)

Path

syntax
optional

The syntax in which to receive the received document.

enum (json, original)

"json"

Query

version
optional

string

"1970-01-01"

Responses

HTTP Code

Description

Schema

200

Success

Transportable

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

Consumes

application/json

6.1.11. WebhookInstances

GET a WebhookInstance

GET /webhook_instances/

Description

GET a WebhookInstance from the queue. After processing it successfully, DELETE it and GET the next one. When a 204 is received, the queue is empty and the polling process can sleep for a while.

Responses

HTTP Code

Description

Schema

200

Success

WebhookInstance

204

Success

No Content

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

DELETE a WebhookInstance

DELETE /webhook_instances/{guid}

Description

DELETE a specific WebhookInstance

Parameters

Type

Name

Description

Schema

Path

guid
required

WebhookInstance guid

string (uuid)

Responses

HTTP Code

Description

Schema

204

Success

No Content

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

6.2. Definitions

6.2.1. AccountingCustomerParty

The customer receiving the document.

Name

Description

Schema

party
required

Party

publicIdentifiers
optional

A list of legal and tax identifiers for this customer.

< PublicIdentifier > array

6.2.2. AccountingSupplierParty

The supplier sending the invoice. When you are doing the sending, most data for the AccountingSupplierParty is taken from the LegalEntity in the Storecove database, where your sender identity resides and has been validated. However, we provide a limited number of fields (mainly contact fields) here that you can specify on a document-by-document basis. For receiving, the full party object can be received.

Name

Description

Schema

party
optional

Party

publicIdentifiers
optional

A list of legal and tax identifiers for this supplier.

< PublicIdentifier > array

6.2.3. AdditionalItemProperty

An additional property for the item

Name Description Schema

name
required

The name of the property.
Minimum length : 1

string

value
required

The value of the property.

string

6.2.4. AdditionalTaxIdentifier

Name Description Schema

country
optional

The ISO3166 country code to use this identifier for in case of consumerTaxMode.
Length : 2

string

county
optional

The county/state inside the country code to use this identifier for in case of consumerTaxMode.
Length : 2

string

id
optional

The Storecove assigned id for the AdditionalTaxIdentifier.

integer (int64)

identifier
optional

The identifier.

string

scheme
optional

The scheme of the identifier.
Length : 2 - 64

string

superscheme
optional

The superscheme of the identifier.
Length : 2 - 64

string

6.2.5. AdditionalTaxIdentifierCreate

Name Description Schema

country
required

The ISO3166 country code to use this identifier for in case of consumerTaxMode.
Length : 2

string

county
optional

The county/state inside the country code to use this identifier for in case of consumerTaxMode. Leave empty to create an additional tax identifier for the entire country. For India, use the two last characters of ISO 3166-2:IN (https://en.wikipedia.org/wiki/States_and_union_territories_of_India).
Length : 2

string

identifier
required

The identifier.

string

scheme
required

The scheme of the identifier.
Length : 2 - 64

string

superscheme
required

The superscheme of the identifier. Should always be "iso6523-actorid-upis".
Length : 2 - 64

string

third_party_password
optional

The password to use to authenticate to a system through which to send the document, or to obtain tax authority approval to send it. This field is currently relevant only for India and mandatory when creating an IN tax identifier.
Length : 2 - 64

string

third_party_username
optional

The username to use to authenticate to a system through which to send the document, or to obtain tax authority approval to send it. This field is currently relevant only for India and mandatory when creating an IN tax identifier.
Length : 2 - 64

string

6.2.6. AdditionalTaxIdentifierUpdate

Name Description Schema

identifier
required

The identifier.

string

third_party_password
optional

string

third_party_username
optional

string

6.2.7. Address

The address

Name Description Schema

city
optional

The name of the city. Mandatory in most countries.
Minimum length : 2

string

country
required

Country

county
optional

An optional county name.

string

street1
optional

The street name and number. Mandatory in most countries.
Minimum length : 2

string

street2
optional

The second street field. Use this if you used the first field for the building name.

string

zip
optional

The zipcode/postalzone. Mandatory unless the country does not have zip codes.
Minimum length : 2

string

6.2.8. Administration

Name Description Schema

email
optional

The email address to send the received document to
Length : 5 - 128

string

id
optional

The Storecove assigned id for the Administration.

integer (int64)

legal_entity_id
optional

The LegalEntity the Administration belongs to.

integer (int64)

package_version
optional

The version of the package.

enum (peppol_bis_v3, aunz, sg)

packaging
optional

How to package the purchase invoice.

enum (ubl)

sender_email_identity_id
optional

The id of the SenderEmailIdentity. If not provided, the Storecove default sender will be used

integer (int64)

6.2.9. AdministrationCreate

Name Description Schema

email
optional

The email address to send the received document to
Length : 5 - 128

string

legal_entity_id
optional

The LegalEntity the Administration belongs to.

integer (int64)

package_version
optional

The version of the package.
Default : "peppol_bis_v3"

enum (peppol_bis_v3, aunz, sg)

packaging
optional

How to package the purchase invoice.
Default : "ubl"

enum (ubl)

sender_email_identity_id
optional

The id of the SenderEmailIdentity. If not provided, the Storecove default sender will be used

integer (int64)

6.2.10. AdministrationUpdate

Name Description Schema

email
optional

The email address to send the received document to
Length : 5 - 128

string

package_version
optional

The version of the package.

enum (peppol_bis_v3, aunz, sg)

packaging
optional

How to package the purchase invoice.

enum (ubl)

sender_email_identity_id
optional

The id of the SenderEmailIdentity. If not provided, the Storecove default sender will be used

integer (int64)

6.2.11. AllowanceCharge

Name Description Schema

amountExcludingTax
optional

The amount for the allowance or charge, excluding tax.

number

amountExcludingVat
optional

DEPRECATED. Use amountExcludingTax. The amount for the allowance or charge, excluding VAT.

number

amountIncludingTax
optional

The amount for the allowance or charge, including tax.

number

baseAmountExcludingTax
optional

The base amount for the allowance or charge, excluding tax.

number

baseAmountIncludingTax
optional

The base amount for the allowance or charge, including tax.

number

reason
optional

The reason for the allowance or charge, free text
Default : "Agreed settlement"

string

reasonCode
optional

DEPRECATED. Do not use. Contact Storecove first if you want to use this field.

string

tax
optional

DEPRECATED. Use the taxesDutiesFees array. The tax for this allowance or charge.

Tax

taxesDutiesFees
optional

An array of taxes, duties and fees for this invoice line. At this moment, multiple Tax items is allowed only for IN (India) and US (USA) taxes. All other countries can only have a single Tax item in this array.

< Tax > array

6.2.12. Attachment

A document attachment to the invoice.

Name Description Schema

description
optional

A description for the file attachment.
Maximal length : 1024

string

document
required

The base64 encoded version of the document attachment.
Minimum length : 5

string

documentId
optional

An id for the file attachment.
Maximal length : 64

string

filename
optional

The name of the file attachment.
Pattern : "^[a-zA-Z0-9]([a-zA-Z0-9.-]*[a-zA-Z0-9])?\\.[a-zA-Z0-9-]+$"

string

mimeType
required

The document attachment mime type. The mime type 'application/xml' can only be used when routing via Peppol to DE:LWID identifier '99661-PEPPOLVERIFIKATION-25' or identifier '991-55555PEPPO-82'

enum (application/pdf, application/xml)

primaryImage
optional

DEPRECATED. Whether or not this document is a visual representation of the invoice data. Note that using value 'true' is discouraged, since the invoice data itself is leading, not the image, and including an image may lead to confusion. Peppol no longer allows including primary images.
Default : false

boolean

6.2.13. BuyerCustomerPartyOrder

The buyer sending the order.

Name

Schema

party
required

SenderParty

6.2.14. Contact

Contact details for the invoice

Name Description Schema

email
optional

string (email)

firstName
optional

string

id
optional

Only supported for AccountingCustomerParty.
Maximal length : 20

string

lastName
optional

string

phone
optional

Maximal length : 24

string

6.2.15. CorpPass

Name Description Schema

client_redirect_fail_url
optional

The URL the CorpPass system will redirect to in case of a failure to perform identity verfication.
Length : 11 - 255

string

client_redirect_success_url
optional

The URL the CorpPass system will redirect to in case of successful identity verfication.
Length : 11 - 255

string

corppass_url
optional

The CorpPass redirect URL.
Length : 11 - 255

string

enabled
optional

Whether or not the CorpPass flow is enabled.
Default : false

boolean

flow_type
optional

The CorpPass flow type.

enum (corppass_flow_redirect, corppass_flow_email, corppass_flow_pdf)

signer_email
optional

The email of the person who is going to perform the CorpPass process.
Length : 2 - 128

string

signer_name
optional

The name of the person who is going to perform the CorpPass process.
Length : 2 - 64

string

simulate_corppass
optional

Whether or not CorpPass is being simulated.
Default : false

boolean

status
optional

The status of the CorpPass process.

enum (corppass_no_status,, corppass_initiated,, corppass_cancelled,, corppass_failed,, corppass_succeeded)

6.2.16. CorpPassCreate

Name Description Schema

client_redirect_fail_url
optional

The URL the CorpPass system will redirect to in case of a failure to perform identity verfication. Mandatory for flow_type="corppass_flow_redirect"
Length : 11 - 255

string

client_redirect_success_url
optional

The URL the CorpPass system will redirect to in case of successful identity verfication. Mandatory for flow_type="corppass_flow_redirect"
Length : 11 - 255

string

enabled
optional

DEPRECATED. Whether or not to enable the CorpPass flow. Must be true if provided.
Default : true

boolean

flow_type
required

The CorpPass flow type. Note that using corppass_flow_pdf requires special setup of your account by Storecove.

enum (corppass_flow_redirect, corppass_flow_email, corppass_flow_pdf)

kyc_document
optional

The Base64-encoded PDF document used for KYC. Mandatory for flow_type="corppass_flow_pdf"

string

signer_email
optional

The email of the person who is going to perform the CorpPass process. Mandatory for flow_type="corppass_flow_email"
Length : 2 - 128

string

signer_name
optional

The name of the person who is going to perform the CorpPass process. Mandatory for flow_type="corppass_flow_email"
Length : 2 - 64

string

simulate_corppass
optional

Whether or not to simulate CorpPass. Instead of redirecting to a CorpPass URL, you will receive a redirect to a Storecove URL which will show a page with two buttons: success and fail. This makes development without having test CorpPass credentials possible. Note this only works in sandbox, not in the production environment.
Default : false

boolean

6.2.17. Country

An ISO 3166-1 alpha-2 country code.

Type : enum (AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW, XK, XI)

6.2.18. CountrySpecification

Name

Description

Schema

country
optional

The ISO 3166-2 country this specification is for.

Country

receiver
optional

The receiver of the document.

Receiver

region
optional

The region this country belongs to. Within this region exchanging invoices is well defined. Between regions some care needs to be taken and Storecove may help in automatically converting some items. Contact us for details of inter-regional document exchange.

enum (eu_eea, sg, aunz, in, world)

sender
optional

The sender of the document.

Sender

Receiver

Name

Description

Schema

business
optional

The business receiver of the document.

Business Receiver

consumer
optional

The consumer receiver of the document.

Consumer Receiver

government
optional

The government receiver of the document.

Government Receiver

Business Receiver

Name

Description

Schema

legal
optional

The legal identifier of the business receiver.

CountrySpecificationIdentifier

routing
optional

The routing identifier of the business receiver.

CountrySpecificationIdentifier

tax
optional

The tax identifier of the business receiver.

CountrySpecificationIdentifier

Consumer Receiver

Name

Description

Schema

legal
optional

The legal identifier of the consumer receiver.

CountrySpecificationIdentifier

routing
optional

The routing identifier of the consumer receiver.

CountrySpecificationIdentifier

tax
optional

The tax identifier of the consumer receiver.

CountrySpecificationIdentifier

Government Receiver

Name

Description

Schema

legal
optional

The legal identifier of the government receiver.

CountrySpecificationIdentifier

routing
optional

The routing identifier of the government receiver.

CountrySpecificationIdentifier

tax
optional

The tax identifier of the government receiver.

CountrySpecificationIdentifier

Sender

Name

Description

Schema

legal
optional

The legal identifier of the sender.

CountrySpecificationIdentifier

tax
optional

The tax identifier of the sender.

CountrySpecificationIdentifier

6.2.19. CountrySpecificationIdentifier

Name

Description

Schema

centalized_identifier_test
optional

The centralized identifier to use for routing in test cases, if the "centralized" proprerty is true. May not always be available depending on the country and network.

string

centralized
optional

Whether or not the identifier represents a centralized routing identifier. This is used in SG, AT and FR where all government invoices are routed to a central accesspoint with a single identifier. This field can only be present for routing identifiers.

boolean

centralized_identifier
optional

The centralized identifier to use for routing, if the "centralized" proprerty is true.

string

description
optional

Identifier description.

string

scheme
optional

The scheme of the identifier

string

scheme_numercial
optional

The numerical version of the scheme of the identifier

string

scheme_type
optional

The scheme type of the identifier. Currently always "iso6523-actorid-upis"

enum (iso6523-actorid-upis)

6.2.20. CountrySpecifications

Name

Schema

countries
optional

< CountrySpecification > array

6.2.21. CurrencyCode

The ISO 4217 currency code.

Type : enum (AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHE, CHF, CHW, CLF, CLP, CNY, COP, COU, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MXV, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLE, SLL, SOS, SRD, SSP, STN, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, USN, UYI, UYU, UZS, VEF, VND, VUV, WST, XAF, XAG, XAU, XBA, XBB, XBC, XBD, XCD, XDR, XFU, XOF, XPD, XPF, XPT, XSU, XTS, XUA, XXX, YER, ZAR, ZMW)

6.2.22. Delivery

Name Description Schema

actualDeliveryDate
optional

The actual date of the delivery. Used only for Invoice
Pattern : "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"

string

deliveryLocation
optional

deliveryLocation

deliveryParty
optional

The party to whom the delivery takes place.

DeliveryParty

deliveryPartyName
optional

DEPRECATED. Use deliveryParty. The name of the party that took delivery. Used only for Invoice

string

quantity
optional

The quantity of the delivery. Used only for Invoice

number

requestedDeliveryPeriod
optional

The requested delivery period. Used only for DocumentOrder. Will also be used for DocumentOrder order lines, if that order line does not specify its own delivery period.
Pattern : "^[0-9]{4}-[0-9]{2}-[0-9]{2} - [0-9]{4}-[0-9]{2}-[0-9]{2}$"

string

shipment
optional

The shipment for the delivery.

Shipment

shippingMarks
optional

DEPRECATED. Use the shipment object. A text that the buyer requests to be printed on the packing labels. Used only for DocumentOrder.
Maximal length : 128

string

deliveryLocation

Name Description Schema

address
optional

The address of the delivery location.

Address

id
optional

The location identifier.
Minimum length : 2

string

locationName
optional

The name of the delivery location. Only used for DocumentOrder.
Maximal length : 128

string

schemeAgencyId
optional

DEPRECATED. The schemeAgencyId of the location identifier (e.g. 'ZZZ')

string

schemeId
optional

The schemeId of the location identifier (e.g. 'EAN')

string

6.2.23. DeliveryParty

The party receiving the shipment.

Name

Description

Schema

party
required

ReceiverParty

publicIdentifiers
optional

A list of legal and tax identifiers for this delivery party.

< PublicIdentifier > array

6.2.24. DeliveryTerms

Name Description Schema

deliveryLocationId
optional

The location to which the delivery terms refer.
Maximal length : 128

string

incoterms
optional

The incoterms:

EXW – Ex Works
The seller must give the buyer access to goods at an agreed location. From that moment, the buyer bears almost all costs and risks during the entire shipping process.
FCA – Free Carrier
The seller must make the goods available at his own risk and expense at his own premises or at an agreed place. In both cases, the seller is responsible for the clearance of the goods for export. It can be agreed that the buyer must instruct the carrier to transfer a “Bill of Lading (BL)” with a note on board to the seller.
CPT – Carriage Paid To
The seller has the same responsibilities as with FCA, but in this case also pays the delivery costs.
CIP – Carriage Insurance Paid To
The same seller responsibilities as with CPT, only in this case the seller is obliged to pay the insurance with a high coverage ratio. Parties can agree separately to apply limited coverage.
DAP – Delivered At Place
The seller bears the costs and risks during the transport of the goods to an agreed address. As soon as the goods have arrived at this address and are ready for unloading, the risk passes to the buyer.
DPU – Delivered at Place Unloaded
The seller is responsible for the costs and risks of delivering goods to an agreed destination where goods can be unloaded for further transport. The selling party arranges customs and unloads the goods at the agreed place. The buyer arranges the customs clearance and any associated rights.
DDP – Delivered Duty Paid
The seller bears the costs and risks of transport, carries out the export and import responsibilities and pays any import duties. As soon as the goods have arrived at the address and are ready for unloading, the risk passes to the buyer.
FAS – Free Alongside Ship
The seller bears all costs and risks until the goods are delivered next to the ship. From that point, the risk is for the buyer and he also arranges the export clearance and import clearance.
FOB – Free On Board
The seller bears all costs and risks until the goods are on board the ship and also arranges the export clearance. As soon as the goods have been delivered to the ship, the buyer bears all responsibilities.
CFR – Cost And Freight
The same applies to the seller and buyer as with FOB, but in this case, the seller must also pay for the transport of the goods to the port.
CIF – Cost, Insurance, and Freight
The seller has the same obligations as with CFR but also pays the (minimum) insurance costs. The buyer must pay for more comprehensive insurance.

enum (EXW, FCA, CPT, CIP, DAP, DPU, DDP, FAS, FOB, CFR, CIF)

specialTerms
optional

A description of special conditions relating to the delivery terms.
Maximal length : 512

string

6.2.25. DiscoverableParticipant

A participant to be discovered.

Name Description Schema

documentTypes
optional

An array of document types to discover. The default is '["invoice", "creditnote"]'. This is ignored when only checking existence.

< enum (invoice, creditnote, invoice_response, order, ordering, order_response) > array

flags
optional

The flags for the check.

DiscoveryFlag

identifier
required

The actual identifier.
Minimum length : 1

string

metaScheme
optional

The meta scheme of the identifier. For Peppol this is always 'iso6523-actorid-upis'.
Default : "iso6523-actorid-upis"
Minimum length : 3

string

network
optional

The network to check. Currently only 'peppol' is supported.
Default : "peppol"
Minimum length : 3

string

scheme
required

The scheme of the identifier. See Receiver Identifiers for a list.
Minimum length : 3

string

6.2.26. DiscoveredParticipant

A public identifier for this customer.

Name

Description

Schema

code
optional

The response code.

enum (OK, NOK)

email
optional

Whether or not an 'OK' response means the document will be sent via Peppol, but delivered by email. This happens in the Belgian Hermes system where all identifiers have been registered, but if the receiver hasn’t registered with a service provider, the Hermes system will send a PDF created from the electronic invoice and email that. The electronic document will itself not be emailed. Also see Hermes.

boolean

6.2.27. DiscoveryFlag

A flag to filter for documents

Name Description Schema

supportsSelfBilling
optional

Whether or not to filter for documents that support self billing.
Default : "not_allowed"

enum (allowed, required, not_allowed)

6.2.28. DocumentInvoiceResponse

The invoice response to send or received.

Name Description Schema

clarifications
optional

A list of clarifications why a received invoice was rejected (RE) or under query (UQ) and what action to take.

< InvoiceResponseClarification > array

effectiveDate
optional

The date when the status became effective. Format: yyyy-mm-dd.
Pattern : "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"

string

note
optional

A note to add to the invoice reponse

string

responseCode
required

The response code. For details see https://docs.peppol.eu/poacc/upgrade-3/codelist/UNCL4343-T111/

enum (AB, IP, UQ, CA, RE, AP, PD)

6.2.29. DocumentOrder

The order to send.

Name Description Schema

accountingCost
optional

The buyer’s accounting cost centre for this document.
Minimum length : 1

string

allowanceCharges
optional

An array of allowance charges.

< AllowanceCharge > array

amountIncludingTax
required

Total amount including Tax.

number

attachments
optional

An array of attachments. You may provide up to 10 attchments, but the total size must not exceed 100MB after Base64 encoding.

< Attachment > array

buyerCustomerParty
optional

The party sending the order. Most data for the BuyerCustomerParty is taken from the Storecove database, where your sender identity resides and has been validated. However, we provide a limited number of fields (mainly contact fields) here that you can specify on a document-by-document basis.

BuyerCustomerPartyOrder

delivery
optional

The delivery information for the document.

Delivery

deliveryTerms
optional

The terms of delivery for the document.

DeliveryTerms

documentCurrencyCode
optional

The documentCurrencyCode is the currency for the entire invoice. We currently do not support invoices in multiple currencies. If left out, will default to EUR

CurrencyCode

documentNumber
required

The number you assigned to the document.
Minimum length : 1

string

issueDate
required

Format: yyyy-mm-dd.
Pattern : "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"

string

issueTime
optional

Format: hh:mm:ss
Pattern : "^[0-9]{2}:[0-9]{2}:[0-9]{2}$"

string

note
optional

A note to add to the document
Maximal length : 255

string

orderLines
required

An array of order lines.

< OrderLine > array

orderType
optional

The type of this order.
Default : "regular"

enum (regular, consignment)

paymentTerms
optional

The payment terms of the document.

PaymentTerms

references
optional

An array of references to other documents. Note that many syntaxes do not support multiple references of the same type in which case they will be concatenated with ','. Also, not all syntaxes and doucments support all documentTypes.

< Reference > array

sellerSupplierParty
required

The seller supplier party. This info will be added to the LegalEntity provided through the legalEntityId.

SellerSupplierParty

taxSystem
optional

The tax system used for the invoice. The system 'tax_line_percentages' is the only one currently supported.
Default : "tax_line_percentages"

enum (tax_line_percentages)

timeZone
optional

Format: ±zzzz, where ±zzzz is the difference from UTC, e.g. 0100 or -0900 etc. The timezone will also apply to the document issue date if this field is provided. + **Pattern** : `"^[-]\\d{4}$"`

string

validityPeriod
optional

The period (or specific date) to which the invoice applies. Format: yyyy-mm-dd - yyyy-mm-dd.
Pattern : "^[0-9]{4}-[0-9]{2}-[0-9]{2} - [0-9]{4}-[0-9]{2}-[0-9]{2}$"

string

6.2.30. DocumentSubmission

The document you want Storecove to send, with some meta-data.

Name Description Schema

attachments
optional

DEPRECATED. Use the attachments array inside the 'document' property. An array of attachments. You may provide up to 10 attchments, but the total size must not exceed 100MB after Base64 encoding.

< Attachment > array

createPrimaryImage
optional

DEPRECATED. In the future we will no longer support creating PDF invoices. Whether or not to create a primary image (PDF) if one is not provided. For customers who started from April 1st 2023, the default is false. For customers who started before that, the default is true.

boolean

document
optional

SendableDocument

idempotencyGuid
optional

A guid that you generated for this DocumentSubmission to achieve idempotency. If you submit multiple documents with the same idempotencyGuid, only the first one will be processed and any subsequent ones will trigger an HTTP 422 Unprocessable Entity response.
Length : 36

string

legalEntityId
optional

The id of the LegalEntity this document should be sent on behalf of. Either legalEntityId or receiveGuid is mandatory.

integer

receiveGuid
optional

The GUID that was in the received_document webhook. Either legalEntityId or receiveGuid is mandatory. This field is used for sending response documents, such as InvoiceReponse and OrderResponse.

string

routing
optional

Specifies where the document is to be sent. Can be electronic identifiers or email addresses.

Routing

6.2.31. DocumentSubmissionEvidence

Name

Description

Schema

documents
optional

An array of documents that were sent. For OpenPeppol, this is always a single document (it may contain a PDF inside). For Email, the number of documents depends on the number of attachments, which in turn depends on the country of the receiver. For email, the raw email in RFC822 format is also included.

< DocumentSubmissionEvidenceDocument > array

evidence
optional

The evidence for this transmission.

DocumentSubmissionEvidenceEvidence

guid
optional

The guid for the InvoiceSubmission.

string

network
optional

The network that was used to clear or send the document

enum (storecove, as2, email, peppol, dbnalliance, sdi, in-irp, pt-b2b, ch-qrbill, finvoice, pl-ksef, spain-face, spain-faceb2b, my-lhdnm)

receiver
optional

The legal identifier of the receiver, or the tax identifier if there is no legal identifier.

string

sender
optional

The legal identifier of the sender, or the tax identifier if there is no legal identifier.

string

6.2.32. DocumentSubmissionEvidenceDocument

Name

Description

Schema

document
optional

The URL where the document can be retrieved.

string

expires_at
optional

The datetime the URL expires. Format: 'YYYY-MM-DD HH:mm:ss.'

string

mime_type
optional

The mime type of the document.

enum (message/rfc822, application/xml, application/json, application/pdf, application/pkcs7-mime)

6.2.33. DocumentSubmissionEvidenceEvidence

Name

Description

Schema

long_id
optional

Only used for network my-lhdnm.

string

message_id
optional

The meaning of this field varies, depending on the network. For peppol and dbnaliance, this is the message id of the envelope. For sdi, this is the filename assigned to the document.

string

partner_key
optional

The meaning of this field varies, depending on the network. For my-lhdnm, it is the UUID. For sg-iras, it is the acknowledgementId

string

qr_code
optional

The QR Code assiged by the tax authority or its authorized partner. Used for networks india and pt-b2b.

string

receiving_accesspoint
optional

An identification of the OpenPeppol accesspoint that the invoice was sent to. Only used for exchange networks like peppol and dbnalliance.

string

remote_mta_ip
optional

The IP address of the sending SMTP server. Only used for network "email".

string

reporting_mta
optional

An identification for the sending SMTP. Only used for network "email".

string

signature
optional

The signature assiged by the tax authority or its authorized partner. Used for network india.

string

signature_date_time
optional

The datetime of the signature assiged by the tax authority or its authorized partner. Used for network india.

string

signature_number
optional

The sequence number of the signature assiged by the tax authority or its authorized partner. Used for network india.

string

smtp_response
optional

The response of the receiving SMTP server. Only used for network "email".

string

timestamp
optional

The timestamp of the delivery to the receiving SMTP server. Only used for network "email".

string

transmission_id
optional

The unique id for this transmission. The meaning of this field varies, depending on the network. For peppol and dbnaliance, this is the AS4 transmission id. For sdi and pl-ksef, this is a unique id assigend to the transmission. For sg-iras, it is the correlationId.

string

xml
optional

The XML evidence for the transmission. This is the XML returned by the receiving accesspoint, either OpenPeppol or DBNAlliance.

string

6.2.34. DocumentSubmissionResult

The result of a document submission

Name

Description

Schema

guid
optional

A (V4) GUID for the document submission

string

6.2.35. EIdentifiers

A list of electronic routing identifiers. These are the identifiers used on the Peppol network or for other destinations.

Type : < RoutingIdentifier > array

6.2.36. ErrorModel

Name

Schema

details
optional

string

source
optional

string

6.2.37. Invoice

The invoice to send. Provide either invoice, or invoiceData, but not both.

Name Description Schema

accountingCost
optional

The buyer’s accounting cost centre for this invoice, expressed as text.
Minimum length : 1

string

accountingCurrencyExchangeRate
optional

Rate at which the document currency must be multiplied to convert it into the accounting currency. If included, must be non-zero.

number

accountingCurrencyTaxAmount
optional

The total amount of tax in the accounting currency. If included, must be non-zero.

number

accountingCurrencyTaxAmountCurrency
optional

The currency of the accountingCurrencyTaxAmount. This MUST be different from the documentCurrencyCode, since it makes no sence including this othterwise. Mandatory if accountingCurrencyTaxAmount is provided.

CurrencyCode

accountingCurrencyTaxableAmount
optional

The taxable amount in the accounting currency. If included, must be non-zero.

number

accountingCustomerParty
required

The party the invoice is sent to.

AccountingCustomerParty

accountingSupplierParty
optional

The party sending the invoice. When you are sending, most data for the AccountingSupplierParty is taken from the LegalEntity in the Storecove database, where your sender identity resides and has been validated. However, we provide a limited number of fields (mainly contact fields) here that you can specify on a document-by-document basis. For receiving, the full party object can be received.

AccountingSupplierParty

allowanceCharges
optional

An array of allowance charges.

< AllowanceCharge > array

amountIncludingTax
optional

EXPERIMENTAL for sending. The amountIncludingTax is the payable amount, but not corrected for the prepaid amount.

number

amountIncludingVat
optional

The amountIncludingVat is payable amount, but not corrected for the prepaid amount. We encourage you to use the amountIncludingTax for sending. For receiving, always use amountIncludingTax.

number

attachments
optional

An array of attachments. You may provide up to 10 attchments, but the total size must not exceed 100MB after Base64 encoding.

< Attachment > array

billingReference
optional

DEPRECATED. Use a reference object with a documentType 'billing'. A reference to a commercial invoice or corrective invoice of which the current invoice is a correction. This field is mandatory when sending invoiceType 384.

string

buyerReference
optional

DEPRECATED. Use a reference object with a documentType 'buyer_reference'. A reference provided by the buyer used for internal routing of the document.

string

consumerTaxMode
optional

Whether or not to process the invoice in consumer tax mode. In this mode, the VAT identifier of the sender will not be the default VAT identifier, but the one that matches with the country of the receiving consumer, if that additional VAT identifier for that country is available. These additional VAT identifiers need to be added to the sending LegalEntity by Storecove, so if you need to send invoices in this mode, please contact us. Not used for receiving.
Default : false

boolean

contractDocumentReference
optional

DEPRECATED. Use a reference object with a documentType 'contract'. A reference to a contract or framework agreement that this invoice relates to.

string

delivery
optional

The delivery of the invoice.

Delivery

deliveryTerms
optional

The terms of delivery for the document. This is currently only used for MY LHDNM.

DeliveryTerms

documentCurrencyCode
optional

The documentCurrencyCode is the currency for the entire invoice. We currently do not support invoices in multiple currencies. If left out, will default to EUR

CurrencyCode

dueDate
optional

Format: yyyy-mm-dd.
Pattern : "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"

string

invoiceLines
required

An array of invoice lines.

< InvoiceLine > array

invoiceNumber
required

The invoice number you assigned to the invoice. The invoiceNumber should be unique for the legalEntityId and year of the issueDate. This means invoice numbers can be reused in different years, as is customary in some countries.
Minimum length : 1

string

invoicePeriod
optional

The period (or specific date) to which the invoice applies. Format: yyyy-mm-dd - yyyy-mm-dd.
Pattern : "^[0-9]{4}-[0-9]{2}-[0-9]{2} - [0-9]{4}-[0-9]{2}-[0-9]{2}$"

string

invoiceType
optional

DEPRECATED. Do not use. This field is available for legacy reasons only. If you want to send a regular invoice (aka UBL type '380'), make sure you have a positive invoice amount. For a credit note (aka UBL type '381'), simply provide a negative invoice amount. If you, in addition to a negative invoice amount, also specify a billingReferences, your invoice will become a corrective invoice (aka UBL type '384'). If your invoice is not sent in the UBL syntax, Storecove will provide the appropriate type for the syntax the invoice is sent in.
Default : "380"

enum (380, 381, 383, 384, 389)

issueDate
required

Format: yyyy-mm-dd.
Pattern : "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"

string

issueReasons
optional

An array reasons for issuing the invoice.

< string > array

issueTime
optional

Format: hh:mm:ss
Pattern : "^[0-9]{2}:[0-9]{2}:[0-9]{2}$"

string

note
optional

A note to add to the invoice

string

orderReference
optional

DEPRECATED. Use a reference object with a documentType 'purchase_order'. A reference to an order for this invoice, assigned by the buyer. Note that this often is a key field, since many receivers of invoices will use this field to automatically match the invoice to an order they placed. Many receivers refuse invoices that cannot be automatically matched, in particular government agencies. So it is highly recommended to fill this field whenever possible.

string

payableRoundingAmount
optional

The rounding amount for the payable amount. This amount is calulated automatically from the invoiceLines, allowanceCharges and the taxSubtotals. If you provide this field, it must be exactly what we would have calculated. We recommend not using this field for sending. For receiving, it is always present.

number

paymentMeansArray
optional

An array of payment means (ways to pay the invoice).

< PaymentMeans > array

paymentMeansBic
optional

DEPRECATED. Use paymentMeansArray. The BIC (Swift) of the bank where the amount payable should be transferred to
Pattern : "^[A-Z]{6}[2-9A-Z][0-9A-NP-Z]([A-Z0-9]{3}|X{3})?$"

string

paymentMeansCode
optional

DEPRECATED. Use paymentMeansArray. How the invoice has been / will be paid. Use only online_payment_service (payment will be made or has been made by an online payment service), bank_card (e.g. debit card, credit card), direct_debit (the amount has been / will be taken out of the client’s bank account), standing_agreement (an unspecified payment means known to both buyer and seller) or credit_transfer (the buyer will do / has done a bank transfer). The numeric codes are for legacy purposes, they should not be used.

enum (online_payment_service, bank_card, direct_debit, standing_agreement, credit_transfer, se_bankgiro, se_plusgiro, aunz_npp, , 1, 30, 31, 42, 48, 49, 57, 58)

paymentMeansIban
optional

DEPRECATED. Use paymentMeansArray. The IBAN the amount payable should be transferred to

string

paymentMeansPaymentId
optional

DEPRECATED. Use the paymentId in the individual PaymentMeans object. The payment id that you will use to match the payment against the invoice.

string

paymentTerms
optional

The payment terms of the invoice.

PaymentTerms

preferredInvoiceType
optional

In autodetect mode, the choice is made by Storecove based on what is appropriate for the receiver and the receiver country, in combination with the invoice amount sign. If you wish to state a preference, use this field. It is not guaranteed that the preference will be used, since it depends also on the receiver’s document capabilities. Only used for sending, not for receiving. For Peppol, only invoice and creditnote are supported. For LHDNM, also debitnote and refundnote are supported. Anything starting it_td* can only be used for SDI. Only used for sending, not present for receiving.
Default : "prefer_autodetect"

enum (prefer_autodetect, prefer_invoice, prefer_creditnote, prefer_debitnote, prefer_refundnote, prefer_corrected_invoice, prefer_it_td02, prefer_it_td19, prefer_it_td24)

prepaidAmount
optional

The amount already paid. The amountInclucingTax - prepaidAmount is the amount remaining to be paid.

number

priceMode
optional

The price mode. This is used to determine whether the prices are net or gross. Price Mode 'price_mode_gross' can only be used for sender countries ES, IT and PT, "clearWithoutSending": true and "taxSystem": "tax_line_percentages". Only used for sending, not present for receiving.
Default : "price_mode_net"

enum (price_mode_net, price_mode_gross)

projectReference
optional

DEPRECATED. Information about the project this invoice relates to.

string

references
optional

< Reference > array

salesOrderId
optional

DEPRECATED. Use a reference object with a documentType 'sales_order'. A reference to an order for this invoice, assigned by the seller.

string

selfBillingMode
optional

There are two reasons for using self billing mode:

The buyer generated the invoice and it needs to be sent to the seller. When sending via Peppol, the receiver needs to support this by advertising a special "self-billing" document type. Otherwise, an email will be sent.
An invoice was received that needs to be reported as a purchase invoice to a tax authority.

When sending in this mode the buyer ("AccountingCustomerParty") and the seller ("AccountingSupplierParty") are automatically switched. That means you still provide the same legalEntityId for the sender (who is now the buyer) and the accountingCustomerParty object is still the receiver (but it is now the seller). That means no changes to the JSON are necessary.

When reporting a received invoice to a tax authority, set the "clearWithoutSending": true flag. Otherwise, the invoice will be reported _and_ sent back to the sender!

This field is only used for sending. We currently do not set this for receiving although that is on the roadmap.

Default : false

boolean

subType
optional

The document subtype. Only used for received invoices, not for sending.

enum (invoice, creditnote, debitnote, correctioninvoice, selfbilling)

taxExemptReason
optional

DEPRECATED. Use Tax/category and specify this per invoice line. If you do specify this field, it will be applied to all invoice lines and it is an error to specify a Tax/category at the invoice line level. This field holds the reason no tax is present in the invoice. Note that this is an invoice level field and you cannot specify it per invoice line. This field is mandatory unless tax is present in the invoice.

enum (export, reverse_charge, zero_rated, exempt, outside_scope, intra_community)

taxPointDate
optional

The tax date is the date on which the supply of goods or of services was made or completed or the date on which the payment on account was made insofar as that date can be determined and differs from the date of the issue of the invoice. EU 2006-112 Article 226 Point 7. Note: For the Dutch TAX authorities the tac date should be the same as the issue date.
Pattern : "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"

string

taxSubtotals
optional

An array of tax subtotals. This element is mandatory for taxSystem 'tax_line_percentages'.

< TaxSubtotal > array

taxSystem
optional

The tax system used for the invoice. The system 'tax_line_percentages' is preferred, but for historic purposes 'tax_line_amounts' is supported and the default. Since not all invoice formats that we are required to send support 'tax_line_amounts' we will need to convert the invoice to the 'tax_line_percentags' system if we are forced to send the invoice in that tax system. Note that an invoice must always contain tax information, even if that is 0% or an item or sender is exempt or tax is completely outside scope. In that case, use the correct tax categories (see Tax)
Default : "tax_line_amounts"

enum (tax_line_amounts, tax_line_percentages)

taxesDutiesFees
optional

An array of taxes, duties and fees for this invoice. At this moment, the only invoice level tax allowed is the Italian '€2 bollo virtuale'

< Tax > array

timeZone
optional

Format: ±zzzz, where ±zzzz is the difference from UTC, e.g. 0100 or -0900 etc. The timezone will also apply to the document issue date if this field is provided. + **Pattern** : `"^[-]\\d{4}$"`

string

transactionType
optional

The type of transaction. Currently used only for India.

enum (b2b, sezwp, sezwop, expwp, expwop, dexp)

ublExtensions
optional

An array of ubl extensions.

< string > array

vatReverseCharge
optional

DEPRECATED. Use taxExemptReason.
Default : false

boolean

x2y
optional

The type of entities the document is sent from/to: b2b (business-to-business), b2g (business-to-government) or b2c (business-to-consumer). This field does not have a default, but it in mose cases it will be treated as b2b. Only when you explicitly specify b2g or b2c OR when it is clear from the context will a different value be used. For instance, when we see the document is being routed to DE:LWID or NL:OINO number, this tells us it is b2g. But in many cases we are unable to determine this and so it is best to always specify this field. Note that b2b_sez is for use inside India only. This field is for sending only.
Default : "b2b"

enum (b2b, b2g, b2c, b2b_sez)

6.2.38. InvoiceData

DEPRECATED. Use RawDocumentData. The invoice to send, in base64 encoded format. Provide either invoice, or invoiceData, but not both.

Name Description Schema

conversionStrategy
optional

How to interpret the document.

enum (ubl, cii, idoc, setu14)

document
optional

The base64 encoded version of the document.
Minimum length : 5

string

6.2.39. InvoiceLine

Name Description Schema

accountingCost
optional

The buyer’s accounting cost centre for this invoice line, expressed as text.
Minimum length : 1

string

additionalItemProperties
optional

An array of additional item properties.

< AdditionalItemProperty > array

allowanceCharge
optional

DEPRECATED. Use allowanceCharges. The discount or surcharge on this item. Should be negative for discounts

number

allowanceCharges
optional

An array of allowances and charges.

< LineAllowanceCharge > array

amountExcludingTax
optional

The amount excluding tax. EXPERIMENTAL for sending. Should equal quantity x itemPrice + allowanceCharge.

number

amountExcludingVat
optional

The amount excluding tax. Should equal quantity x itemPrice + allowanceCharge.

number

amountIncludingTax
optional

The amount including tax. Can only be used for "priceMode": "price_mode_gross". Use either this property or amountExcludingTax (amountExcludingVat).

number

baseQuantity
optional

The number of items (may be fractional) the itemPrice is for.

number

buyersItemIdentification
optional

DEPRECATED. Use the references array with 'line_buyers_item_identification' documentType. The ID the buyer assigned to this item.
Minimum length : 1

string

description
optional

The description for this invoice line.
Minimum length : 1

string

invoicePeriod
optional

The period (or specific date) to which the invoice line applies. Format: yyyy-mm-dd - yyyy-mm-dd.
Pattern : "^[0-9]{4}-[0-9]{2}-[0-9]{2} - [0-9]{4}-[0-9]{2}-[0-9]{2}$"

string

itemPrice
optional

The price per item (may be fractional)

number

lineId
optional

The id for this invoice line.
Length : 1 - 36

string

name
optional

A short name for this invoice line. If not provided, it will be taken from description and description will be set to an emtpy string.
Minimum length : 1

string

note
optional

A note to add to the document line

string

orderLineReferenceLineId
optional

DEPRECATED. Use a reference with type 'line_purchase_order'. A reference to the LineID of the order. The order itself is specified as the orderReference at the invoice level. It is not possible to specify an orderReference at the invoice line level. An invoice MUST at this time be for a single order only.
Minimum length : 1

string

quantity
optional

The number of items (may be fractional).

number

quantityUnitCode
optional

The unit of measure that applies to the invoiced quantity. Codes for unit of packaging from UNECE Recommendation No. 21 can be used in accordance with the descriptions in the "Intro" section of UN/ECE Recommendation 20, Revision 11 (2015): The 2 character alphanumeric code values in UNECE Recommendation 21 shall be used. To avoid duplication with existing code values in UNECE Recommendation No. 20, each code value from UNECE Recommendation 21 shall be prefixed with an “X”, resulting in a 3 alphanumeric code when used as a unit of measure. Note that the following additionally allowed codes are deprecated and will be converted to C62: 04, 05, 08, 16, 17, 18, 19, 26, 29, 30, 31, 32, 36, 43, 44, 45, 46, 47, 48, 53, 54, 62, 63, 64, 66, 69, 71, 72, 73, 76, 78, 84, 90, 92, 93, 94, 95, 96, 97, 98, 1A, 1B, 1C, 1D, 1E, 1F, 1G, 1H, 1J, 1K, 1L, 1M, 1X, 2V, 2W, 3E, 3G, 3H, 3I, 4A, 4B, 4E, 5C, 5F, 5G, 5H, 5I, 5K, 5P, 5Q, A1, A25, A50, A51, A52, A57, A58, A60, A61, A62, A63, A64, A65, A66, A67, A77, A78, A79, A80, A81, A82, A83, AJ, AM, AP, AR, ARE, ATT, AV, AW, B0, B2, B36, B37, B38, B39, B40, B5, B51, B6, B65, B9, BD, BE, BG, BH, BJ, BK, BL, BO, BR, BT, BW, BX, BZ, C1, C2, C4, C5, C6, C77, C98, CA, CH, CJ, CK, CL, CO, CQ, CR, CS, CT, CU, CV, CY, CZ, D14, D28, D35, D37, D38, D39, D40, D64, D66, D67, D7, D70, D71, D72, D75, D76, D79, D8, D9, D90, D92, D96, D97, D98, D99, DC, DE, DI, DQ, DR, DRM, DS, DU, DX, DY, E2, E3, E5, EC, EP, EV, F1, F9, FB, FD, FE, FG, FM, G7, GC, GD, GH, GK, GN, GRT, GT, GW, GY, GZ, H1, H2, HAR, HD, HE, HF, HI, HJ, HK, HL, HN, HO, HP, HS, HT, HY, IC, IF, II, IL, IM, IP, IT, JB, JG, JO, JR, K5, KD, KF, KG, KS, KTM, LC, LE, LI, LJ, LX, M0, MA, MF, MK, MQ, MT, MV, N2, NB, NBB, NC, ND, NE, NG, NH, NI, NJ, NN, NPL, NPR, NQ, NR, NRL, NTT, NV, NY, OP, OZ, P0, P3, P4, P6, P7, P8, P9, PA, PB, PE, PF, PG, PK, PL, PM, PN, PT, PU, PV, PW, PY, PZ, QD, QH, QK, QT, R4, RA, RD, RG, RK, RL, RN, RO, RS, RU, S5, S6, S7, S8, SA, SD, SE, SHT, SK, SL, SN, SO, SP, SS, SST, ST, SV, T1, T4, T5, T6, T7, T8, TA, TC, TD, TE, TF, TJ, TK, TL, TN, TQ, TR, TS, TSD, TSH, TT, TU, TV, TW, TY, UA, UD, UE, UF, UH, UM, VI, VQ, VS, W4, WH, WI, WR, WW, YL, YT, Z1, Z2, Z3, Z4, Z5, Z6, Z8
Default : "C62"

enum (10, 11, 13, 14, 15, 20, 21, 22, 23, 24, 25, 27, 28, 33, 34, 35, 37, 38, 40, 41, 56, 57, 58, 59, 60, 61, 74, 77, 80, 81, 85, 87, 89, 91, 1I, 2A, 2B, 2C, 2G, 2H, 2I, 2J, 2K, 2L, 2M, 2N, 2P, 2Q, 2R, 2U, 2X, 2Y, 2Z, 3B, 3C, 4C, 4G, 4H, 4K, 4L, 4M, 4N, 4O, 4P, 4Q, 4R, 4T, 4U, 4W, 4X, 5A, 5B, 5E, 5J, A10, A11, A12, A13, A14, A15, A16, A17, A18, A19, A2, A20, A21, A22, A23, A24, A26, A27, A28, A29, A3, A30, A31, A32, A33, A34, A35, A36, A37, A38, A39, A4, A40, A41, A42, A43, A44, A45, A47, A48, A49, A5, A53, A54, A55, A56, A59, A6, A68, A69, A7, A70, A71, A73, A74, A75, A76, A8, A84, A85, A86, A87, A88, A89, A9, A90, A91, A93, A94, A95, A96, A97, A98, A99, AA, AB, ACR, ACT, AD, AE, AH, AI, AK, AL, AMH, AMP, ANN, APZ, AQ, AS, ASM, ASU, ATM, AWG, AY, AZ, B1, B10, B11, B12, B13, B14, B15, B16, B17, B18, B19, B20, B21, B22, B23, B24, B25, B26, B27, B28, B29, B3, B30, B31, B32, B33, B34, B35, B4, B41, B42, B43, B44, B45, B46, B47, B48, B49, B50, B52, B53, B54, B55, B56, B57, B58, B59, B60, B61, B62, B63, B64, B66, B67, B68, B69, B7, B70, B71, B72, B73, B74, B75, B76, B77, B78, B79, B8, B80, B81, B82, B83, B84, B85, B86, B87, B88, B89, B90, B91, B92, B93, B94, B95, B96, B97, B98, B99, BAR, BB, BFT, BHP, BIL, BLD, BLL, BP, BPM, BQL, BTU, BUA, BUI, C0, C10, C11, C12, C13, C14, C15, C16, C17, C18, C19, C20, C21, C22, C23, C24, C25, C26, C27, C28, C29, C3, C30, C31, C32, C33, C34, C35, C36, C37, C38, C39, C40, C41, C42, C43, C44, C45, C46, C47, C48, C49, C50, C51, C52, C53, C54, C55, C56, C57, C58, C59, C60, C61, C62, C63, C64, C65, C66, C67, C68, C69, C7, C70, C71, C72, C73, C74, C75, C76, C78, C79, C8, C80, C81, C82, C83, C84, C85, C86, C87, C88, C89, C9, C90, C91, C92, C93, C94, C95, C96, C97, C99, CCT, CDL, CEL, CEN, CG, CGM, CKG, CLF, CLT, CMK, CMQ, CMT, CNP, CNT, COU, CTG, CTM, CTN, CUR, CWA, CWI, D03, D04, D1, D10, D11, D12, D13, D15, D16, D17, D18, D19, D2, D20, D21, D22, D23, D24, D25, D26, D27, D29, D30, D31, D32, D33, D34, D36, D41, D42, D43, D44, D45, D46, D47, D48, D49, D5, D50, D51, D52, D53, D54, D55, D56, D57, D58, D59, D6, D60, D61, D62, D63, D65, D68, D69, D73, D74, D77, D78, D80, D81, D82, D83, D85, D86, D87, D88, D89, D91, D93, D94, D95, DAA, DAD, DAY, DB, DD, DEC, DG, DJ, DLT, DMA, DMK, DMO, DMQ, DMT, DN, DPC, DPR, DPT, DRA, DRI, DRL, DT, DTN, DWT, DZN, DZP, E01, E07, E08, E09, E10, E12, E14, E15, E16, E17, E18, E19, E20, E21, E22, E23, E25, E27, E28, E30, E31, E32, E33, E34, E35, E36, E37, E38, E39, E4, E40, E41, E42, E43, E44, E45, E46, E47, E48, E49, E50, E51, E52, E53, E54, E55, E56, E57, E58, E59, E60, E61, E62, E63, E64, E65, E66, E67, E68, E69, E70, E71, E72, E73, E74, E75, E76, E77, E78, E79, E80, E81, E82, E83, E84, E85, E86, E87, E88, E89, E90, E91, E92, E93, E94, E95, E96, E97, E98, E99, EA, EB, EQ, F01, F02, F03, F04, F05, F06, F07, F08, F10, F11, F12, F13, F14, F15, F16, F17, F18, F19, F20, F21, F22, F23, F24, F25, F26, F27, F28, F29, F30, F31, F32, F33, F34, F35, F36, F37, F38, F39, F40, F41, F42, F43, F44, F45, F46, F47, F48, F49, F50, F51, F52, F53, F54, F55, F56, F57, F58, F59, F60, F61, F62, F63, F64, F65, F66, F67, F68, F69, F70, F71, F72, F73, F74, F75, F76, F77, F78, F79, F80, F81, F82, F83, F84, F85, F86, F87, F88, F89, F90, F91, F92, F93, F94, F95, F96, F97, F98, F99, FAH, FAR, FBM, FC, FF, FH, FIT, FL, FOT, FP, FR, FS, FTK, FTQ, G01, G04, G05, G06, G08, G09, G10, G11, G12, G13, G14, G15, G16, G17, G18, G19, G2, G20, G21, G23, G24, G25, G26, G27, G28, G29, G3, G30, G31, G32, G33, G34, G35, G36, G37, G38, G39, G40, G41, G42, G43, G44, G45, G46, G47, G48, G49, G50, G51, G52, G53, G54, G55, G56, G57, G58, G59, G60, G61, G62, G63, G64, G65, G66, G67, G68, G69, G70, G71, G72, G73, G74, G75, G76, G77, G78, G79, G80, G81, G82, G83, G84, G85, G86, G87, G88, G89, G90, G91, G92, G93, G94, G95, G96, G97, G98, G99, GB, GBQ, GDW, GE, GF, GFI, GGR, GIA, GIC, GII, GIP, GJ, GL, GLD, GLI, GLL, GM, GO, GP, GQ, GRM, GRN, GRO, GV, GWH, H03, H04, H05, H06, H07, H08, H09, H10, H11, H12, H13, H14, H15, H16, H18, H19, H20, H21, H22, H23, H24, H25, H26, H27, H28, H29, H30, H31, H32, H33, H34, H35, H36, H37, H38, H39, H40, H41, H42, H43, H44, H45, H46, H47, H48, H49, H50, H51, H52, H53, H54, H55, H56, H57, H58, H59, H60, H61, H62, H63, H64, H65, H66, H67, H68, H69, H70, H71, H72, H73, H74, H75, H76, H77, H79, H80, H81, H82, H83, H84, H85, H87, H88, H89, H90, H91, H92, H93, H94, H95, H96, H98, H99, HA, HBA, HBX, HC, HDW, HEA, HGM, HH, HIU, HKM, HLT, HM, HMQ, HMT, HPA, HTZ, HUR, IA, IE, INH, INK, INQ, ISD, IU, IV, J10, J12, J13, J14, J15, J16, J17, J18, J19, J2, J20, J21, J22, J23, J24, J25, J26, J27, J28, J29, J30, J31, J32, J33, J34, J35, J36, J38, J39, J40, J41, J42, J43, J44, J45, J46, J47, J48, J49, J50, J51, J52, J53, J54, J55, J56, J57, J58, J59, J60, J61, J62, J63, J64, J65, J66, J67, J68, J69, J70, J71, J72, J73, J74, J75, J76, J78, J79, J81, J82, J83, J84, J85, J87, J90, J91, J92, J93, J95, J96, J97, J98, J99, JE, JK, JM, JNT, JOU, JPS, JWL, K1, K10, K11, K12, K13, K14, K15, K16, K17, K18, K19, K2, K20, K21, K22, K23, K26, K27, K28, K3, K30, K31, K32, K33, K34, K35, K36, K37, K38, K39, K40, K41, K42, K43, K45, K46, K47, K48, K49, K50, K51, K52, K53, K54, K55, K58, K59, K6, K60, K61, K62, K63, K64, K65, K66, K67, K68, K69, K70, K71, K73, K74, K75, K76, K77, K78, K79, K80, K81, K82, K83, K84, K85, K86, K87, K88, K89, K90, K91, K92, K93, K94, K95, K96, K97, K98, K99, KA, KAT, KB, KBA, KCC, KDW, KEL, KGM, KGS, KHY, KHZ, KI, KIC, KIP, KJ, KJO, KL, KLK, KLX, KMA, KMH, KMK, KMQ, KMT, KNI, KNM, KNS, KNT, KO, KPA, KPH, KPO, KPP, KR, KSD, KSH, KT, KTN, KUR, KVA, KVR, KVT, KW, KWH, KWO, KWT, KX, L10, L11, L12, L13, L14, L15, L16, L17, L18, L19, L2, L20, L21, L23, L24, L25, L26, L27, L28, L29, L30, L31, L32, L33, L34, L35, L36, L37, L38, L39, L40, L41, L42, L43, L44, L45, L46, L47, L48, L49, L50, L51, L52, L53, L54, L55, L56, L57, L58, L59, L60, L63, L64, L65, L66, L67, L68, L69, L70, L71, L72, L73, L74, L75, L76, L77, L78, L79, L80, L81, L82, L83, L84, L85, L86, L87, L88, L89, L90, L91, L92, L93, L94, L95, L96, L98, L99, LA, LAC, LBR, LBT, LD, LEF, LF, LH, LK, LM, LN, LO, LP, LPA, LR, LS, LTN, LTR, LUB, LUM, LUX, LY, M1, M10, M11, M12, M13, M14, M15, M16, M17, M18, M19, M20, M21, M22, M23, M24, M25, M26, M27, M29, M30, M31, M32, M33, M34, M35, M36, M37, M38, M39, M4, M40, M41, M42, M43, M44, M45, M46, M47, M48, M49, M5, M50, M51, M52, M53, M55, M56, M57, M58, M59, M60, M61, M62, M63, M64, M65, M66, M67, M68, M69, M7, M70, M71, M72, M73, M74, M75, M76, M77, M78, M79, M80, M81, M82, M83, M84, M85, M86, M87, M88, M89, M9, M90, M91, M92, M93, M94, M95, M96, M97, M98, M99, MAH, MAL, MAM, MAR, MAW, MBE, MBF, MBR, MC, MCU, MD, MGM, MHZ, MIK, MIL, MIN, MIO, MIU, MLD, MLT, MMK, MMQ, MMT, MND, MON, MPA, MQH, MQS, MSK, MTK, MTQ, MTR, MTS, MVA, MWH, N1, N10, N11, N12, N13, N14, N15, N16, N17, N18, N19, N20, N21, N22, N23, N24, N25, N26, N27, N28, N29, N3, N30, N31, N32, N33, N34, N35, N36, N37, N38, N39, N40, N41, N42, N43, N44, N45, N46, N47, N48, N49, N50, N51, N52, N53, N54, N55, N56, N57, N58, N59, N60, N61, N62, N63, N64, N65, N66, N67, N68, N69, N70, N71, N72, N73, N74, N75, N76, N77, N78, N79, N80, N81, N82, N83, N84, N85, N86, N87, N88, N89, N90, N91, N92, N93, N94, N95, N96, N97, N98, N99, NA, NAR, NCL, NEW, NF, NIL, NIU, NL, NM3, NMI, NMP, NPT, NT, NU, NX, OA, ODE, OHM, ON, ONZ, OPM, OT, OZA, OZI, P1, P10, P11, P12, P13, P14, P15, P16, P17, P18, P19, P2, P20, P21, P22, P23, P24, P25, P26, P27, P28, P29, P30, P31, P32, P33, P34, P35, P36, P37, P38, P39, P40, P41, P42, P43, P44, P45, P46, P47, P48, P49, P5, P50, P51, P52, P53, P54, P55, P56, P57, P58, P59, P60, P61, P62, P63, P64, P65, P66, P67, P68, P69, P70, P71, P72, P73, P74, P75, P76, P77, P78, P79, P80, P81, P82, P83, P84, P85, P86, P87, P88, P89, P90, P91, P92, P93, P94, P95, P96, P97, P98, P99, PAL, PD, PFL, PGL, PI, PLA, PO, PQ, PR, PS, PTD, PTI, PTL, PTN, Q10, Q11, Q12, Q13, Q14, Q15, Q16, Q17, Q18, Q19, Q20, Q21, Q22, Q23, Q24, Q25, Q26, Q27, Q28, Q29, Q30, Q31, Q32, Q33, Q34, Q35, Q36, Q37, Q38, Q39, Q40, Q3, QA, QAN, QB, QR, QTD, QTI, QTL, QTR, R1, R9, RH, RM, ROM, RP, RPM, RPS, RT, S3, S4, SAN, SCO, SCR, SEC, SET, SG, SIE, SM3, SMI, SQ, SQR, SR, STC, STI, STK, STL, STN, STW, SW, SX, SYR, T0, T3, TAH, TAN, TI, TIC, TIP, TKM, TMS, TNE, TP, TPI, TPR, TQD, TRL, TST, TTS, U1, U2, UB, UC, VA, VLT, VP, W2, WA, WB, WCD, WE, WEB, WEE, WG, WHR, WM, WSD, WTT, X1, YDK, YDQ, YRD, Z11, ZP, ZZ, X1A, X1B, X1D, X1F, X1G, X1W, X2C, X3A, X3H, X43, X44, X4A, X4B, X4C, X4D, X4F, X4G, X4H, X5H, X5L, X5M, X6H, X6P, X7A, X7B, X8A, X8B, X8C, XAA, XAB, XAC, XAD, XAE, XAF, XAG, XAH, XAI, XAJ, XAL, XAM, XAP, XAT, XAV, XB4, XBA, XBB, XBC, XBD, XBE, XBF, XBG, XBH, XBI, XBJ, XBK, XBL, XBM, XBN, XBO, XBP, XBQ, XBR, XBS, XBT, XBU, XBV, XBW, XBX, XBY, XBZ, XCA, XCB, XCC, XCD, XCE, XCF, XCG, XCH, XCI, XCJ, XCK, XCL, XCM, XCN, XCO, XCP, XCQ, XCR, XCS, XCT, XCU, XCV, XCW, XCX, XCY, XCZ, XDA, XDB, XDC, XDG, XDH, XDI, XDJ, XDK, XDL, XDM, XDN, XDP, XDR, XDS, XDT, XDU, XDV, XDW, XDX, XDY, XEC, XED, XEE, XEF, XEG, XEH, XEI, XEN, XFB, XFC, XFD, XFE, XFI, XFL, XFO, XFP, XFR, XFT, XFW, XFX, XGB, XGI, XGL, XGR, XGU, XGY, XGZ, XHA, XHB, XHC, XHG, XHN, XHR, XIA, XIB, XIC, XID, XIE, XIF, XIG, XIH, XIK, XIL, XIN, XIZ, XJB, XJC, XJG, XJR, XJT, XJY, XKG, XKI, XLE, XLG, XLT, XLU, XLV, XLZ, XMA, XMB, XMC, XME, XMR, XMS, XMT, XMW, XMX, XNA, XNE, XNF, XNG, XNS, XNT, XNU, XNV, XOA, XOB, XOC, XOD, XOE, XOF, XOK, XOT, XOU, XP2, XPA, XPB, XPC, XPD, XPE, XPF, XPG, XPH, XPI, XPJ, XPK, XPL, XPN, XPO, XPP, XPR, XPT, XPU, XPV, XPX, XPY, XPZ, XQA, XQB, XQC, XQD, XQF, XQG, XQH, XQJ, XQK, XQL, XQM, XQN, XQP, XQQ, XQR, XQS, XRD, XRG, XRJ, XRK, XRL, XRO, XRT, XRZ, XSA, XSB, XSC, XSD, XSE, XSH, XSI, XSK, XSL, XSM, XSO, XSP, XSS, XST, XSU, XSV, XSW, XSY, XSZ, XT1, XTB, XTC, XTD, XTE, XTG, XTI, XTK, XTL, XTN, XTO, XTR, XTS, XTT, XTU, XTV, XTW, XTY, XTZ, XUC, XUN, XVA, XVG, XVI, XVK, XVL, XVO, XVP, XVQ, XVN, XVR, XVS, XVY, XWA, XWB, XWC, XWD, XWF, XWG, XWH, XWJ, XWK, XWL, XWM, XWN, XWP, XWQ, XWR, XWS, XWT, XWU, XWV, XWW, XWX, XWY, XWZ, XXA, XXB, XXC, XXD, XXF, XXG, XXH, XXJ, XXK, XYA, XYB, XYC, XYD, XYF, XYG, XYH, XYJ, XYK, XYL, XYM, XYN, XYP, XYQ, XYR, XYS, XYT, XYV, XYW, XYX, XYY, XYZ, XZA, XZB, XZC, XZD, XZF, XZG, XZH, XZJ, XZK, XZL, XZM, XZN, XZP, XZQ, XZR, XZS, XZT, XZU, XZV, XZW, XZX, XZY, XZZ, 04, 05, 08, 16, 17, 18, 19, 26, 29, 30, 31, 32, 36, 43, 44, 45, 46, 47, 48, 53, 54, 62, 63, 64, 66, 69, 71, 72, 73, 76, 78, 84, 90, 92, 93, 94, 95, 96, 97, 98, 1A, 1B, 1C, 1D, 1E, 1F, 1G, 1H, 1J, 1K, 1L, 1M, 1X, 2V, 2W, 3E, 3G, 3H, 3I, 4A, 4B, 4E, 5C, 5F, 5G, 5H, 5I, 5K, 5P, 5Q, A1, A25, A50, A51, A52, A57, A58, A60, A61, A62, A63, A64, A65, A66, A67, A77, A78, A79, A80, A81, A82, A83, AJ, AM, AP, AR, ARE, ATT, AV, AW, B0, B2, B36, B37, B38, B39, B40, B5, B51, B6, B65, B9, BD, BE, BG, BH, BJ, BK, BL, BO, BR, BT, BW, BX, BZ, C1, C2, C4, C5, C6, C77, C98, CA, CH, CJ, CK, CL, CO, CQ, CR, CS, CT, CU, CV, CY, CZ, D14, D28, D35, D37, D38, D39, D40, D64, D66, D67, D7, D70, D71, D72, D75, D76, D79, D8, D9, D90, D92, D96, D97, D98, D99, DC, DE, DI, DQ, DR, DRM, DS, DU, DX, DY, E2, E3, E5, EC, EP, EV, F1, F9, FB, FD, FE, FG, FM, G7, GC, GD, GH, GK, GN, GRT, GT, GW, GY, GZ, H1, H2, HAR, HD, HE, HF, HI, HJ, HK, HL, HN, HO, HP, HS, HT, HY, IC, IF, II, IL, IM, IP, IT, JB, JG, JO, JR, K5, KD, KF, KG, KS, KTM, LC, LE, LI, LJ, LX, M0, MA, MF, MK, MQ, MT, MV, N2, NB, NBB, NC, ND, NE, NG, NH, NI, NJ, NN, NPL, NPR, NQ, NR, NRL, NTT, NV, NY, OP, OZ, P0, P3, P4, P6, P7, P8, P9, PA, PB, PE, PF, PG, PK, PL, PM, PN, PT, PU, PV, PW, PY, PZ, QD, QH, QK, QT, R4, RA, RD, RG, RK, RL, RN, RO, RS, RU, S5, S6, S7, S8, SA, SD, SE, SHT, SK, SL, SN, SO, SP, SS, SST, ST, SV, T1, T4, T5, T6, T7, T8, TA, TC, TD, TE, TF, TJ, TK, TL, TN, TQ, TR, TS, TSD, TSH, TT, TU, TV, TW, TY, UA, UD, UE, UF, UH, UM, VI, VQ, VS, W4, WH, WI, WR, WW, YL, YT, Z1, Z2, Z3, Z4, Z5, Z6, Z8)

references
optional

An array of references to other documents or codes. Note that many syntaxes do not support multiple references of the same type in which case they will be concatenated with ','. Also, not all syntaxes support all documentTypes.

< Reference > array

sellersItemIdentification
optional

DEPRECATED. Use the references array with 'line_sellers_item_identification' documentType. The ID the seller assigned to this item.
Minimum length : 1

string

standardItemIdentification
optional

DEPRECATED. Use 'line_standard_item_identification'. Standardized ID for the item.
Minimum length : 1

string

standardItemIdentificationSchemeAgencyId
optional

DEPRECATED. Use the references array with 'line_standard_item_identification' documentType. The scheme agency for the standardized ID for the item.
Default : "9"
Minimum length : 1

string

standardItemIdentificationSchemeId
optional

DEPRECATED. Use the references array with 'line_standard_item_identification' documentType. The scheme for the standardized ID for the item.
Default : "GTIN"
Minimum length : 1

string

tax
optional

DEPRECATED. Use taxesDutiesFees. The tax for this invoice line.

Tax

taxesDutiesFees
optional

An array of taxes, duties and fees for this invoice line. Multiple taxesDutiesFees items is allowed only for IN (India) and US (USA) taxes. All other countries can only have a single Tax item in this array.

< Tax > array

6.2.40. InvoiceRecipient

DEPRECATED. Use the Routing object. The different ways to send the invoice to the recipient. The publicIdentifiers are used to send via the Peppol network, if the recipient is not registered on the Peppol network, the invoice will be sent to the email addresses in the emails property. This property is only mandatory when sending the invoice data using the Invoice property, not when sending using the InvoiceData property, in which case this information will be extracted from the InvoiceData object. If you do specify an InvoiceRecipient object and an InvoiceData object, the data from the two will be merged.

Name

Description

Schema

emails
optional

The email addresses the invoice should be sent to if none of the other identifiers can be used

< string (email) > array

publicIdentifiers
optional

The public identifiers for this invoice recipient. These are the identifiers used on the Peppol network. Note that when sending invoices with VAT (or with a taxExemptReason), a receiver VAT number is required and that should be one of these publicIdentifiers.

PublicIdentifiers

6.2.41. InvoiceRecipientPreflight

Identifies the invoice recipient to preflight

Name

Description

Schema

publicIdentifiers
optional

The public identifiers for this invoice recipient.

PublicIdentifiers

6.2.42. InvoiceResponseClarification

A clarification for why a received invoice was rejected (RE) or under query (UQ) and what action to take.

Name

Description

Schema

clarification
optional

A textual description of the clarification

string

clarificationCode
optional

The code for the clarification. For details see https://docs.peppol.eu/poacc/upgrade-3/codelist/OPStatusReason/ and https://docs.peppol.eu/poacc/upgrade-3/codelist/OPStatusAction/

enum (NON, REF, LEG, REC, QUA, DEL, PRI, QTY, ITM, PAY, UNR, FIN, PPD, OTH, NOA, PIN, NIN, CNF, CNP, CNA)

clarificationCodeType
optional

The type of the clarification.

enum (OPStatusReason, OPStatusAction)

conditions
optional

A list of conditions that triggered the error. This is only included for receiving in webhooks. You cannot currently send these conditions.

< InvoiceResponseCondition > array

6.2.43. InvoiceResponseCondition

Specifies an error in the received invoice.

Name

Description

Schema

fieldCode
required

The code of the field with the error. Find the element here: https://docs.peppol.eu/poacc/billing/3.0/syntax/ubl-invoice/ and then get the field’s Business term.

string

fieldValue
required

The (error) value of the field.

string

6.2.44. InvoiceSubmission

DEPRECATED. The invoice you want Storecove to process, with some meta-data.

Name Description Schema

attachments
optional

An array of attachments. You may provide up to 10 attchments, but the total size must not exceed 100MB after Base64 encoding.

< Attachment > array

createPrimaryImage
optional

DEPRECATED. In the future we will no longer support creating PDF invoices. Whether or not to create a primary image (PDF) if one is not provided. For customers who started from December 1st 2022, the default is false. For customers who started before that, the default is true.

boolean

document
optional

DEPRECATED. Use attachments.

string

documentUrl
optional

DEPRECATED. Use attachments.

string (uri)

idempotencyGuid
optional

A guid that you generated for this InvoiceSubmission to achieve idempotency. If you submit multiple documents with the same idempotencyGuid, only the first one will be processed.
Length : 36

string

invoice
optional

Invoice

invoiceData
optional

InvoiceData

invoiceRecipient
optional

DEPRECATED. Use the routing and accountingCustomerParty.publicIdentifiers properties.

InvoiceRecipient

legalEntityId
optional

The id of the LegalEntity this invoice should be sent for.

integer

legalSupplierId
optional

DEPRECATED. Use legalEntityId

integer

mode
optional

DEPRECATED.

enum (direct)

routing
optional

Specifies where the invoice is to be sent. Can be electronic identifiers or email addresses.

Routing

supplierId
optional

DEPRECATED.

integer

6.2.45. InvoiceSubmissionActionEvidence

Name

Description

Schema

receiver_response
optional

The response the receiver sent.

string

transmission_datetime
optional

The DateTime of the transmission, as defined by RFC 3339, section 5.6, for example, 2017-07-21T17:32:28Z.

string

transmission_result
optional

The result of this transmission.

enum (unknown, accepted, rejected, send_error, internal_error)

transmission_type
optional

How the document was transmitted.

enum (email, edi, as2, peppol, sandbox)

transmitted_document
optional

The document that was transmitted.

string

6.2.46. InvoiceSubmissionEvidence

Name

Description

Schema

actions
optional

An array of actions taken to deliver the document.

< InvoiceSubmissionActionEvidence > array

guid
optional

The guid for the InvoiceSubmission.

string

status
optional

The overall status for this InvoiceSubmission.

string

6.2.47. InvoiceSubmissionResult

The result of an invoice submission

Name

Description

Schema

guid
optional

A (V4) GUID for the invoice submission

string

6.2.48. LegalEntity

Polymorphism : Composition

Name Description Schema

acts_as_receiver
optional

Whether or not this LegalEntity can act as a receiver of documents. If not, no identifiers will be provioned on any exchange network.
Default : true

boolean

acts_as_sender
optional

Whether or not this LegalEntity can act as a sender of documents.
Default : true

boolean

additional_tax_identifiers
optional

< AdditionalTaxIdentifier > array

advertisements
optional

A list of document types to advertise. Use if this LegalEntity needs the ability to receive more than only invoice documents.

< enum (invoice, invoice_response, order, ordering, order_response, selfbilling) > array

api_keys
optional

< string > array

city
optional

The city.
Length : 2 - 64

string

classification_code
optional

The classification code for this LegalEntity. For Malaysia, this is the MSIC code. It is mandatory for MY legal entities.

string

country
optional

Country

county
optional

County, if applicable
Maximal length : 64

string

id
optional

The Storecove assigned id for the LegalEntity.

integer (int64)

line1
optional

The first address line.
Length : 2 - 192

string

line2
optional

The second address line, if applicable
Maximal length : 192

string

party_name
optional

The name of the company.
Length : 2 - 64

string

peppol_identifiers
optional

< PeppolIdentifier > array

public
optional

Whether or not this LegalEntity is public. Public means it will be listed in the PEPPOL directory at https://directory.peppol.eu/ which is normally what you want. If you have a good reason to not want the LegalEntity listed, provide false. This property is ignored when for country SG, where it is always true.
Default : true

boolean

rea
optional

The REA details for the LegalEntity. Only applies to IT LegalEntities.

Rea

smart_inbox
optional

DEPRECATED. Use the ReceivedDocuments endpoint. The email address of the Smart Inbox for this LegalEntity.

string

tax_registered
optional

Whether or not this LegalEntity is tax registered. This influences the validation of the data presented when sending documents.
Default : true

boolean

tenant_id
optional

The id of the tenant, to be used in case of multi-tenant solutions. This property will included in webhook events.
Maximal length : 64

string

third_party_password
optional

string

third_party_username
optional

string

zip
optional

The zipcode.
Length : 2 - 32

string

6.2.49. LegalEntityCreate

Name Description Schema

acts_as_receiver
optional

Whether or not this LegalEntity can act as a receiver of documents. If not, no identifiers will be provioned on any exchange network.
Default : true

boolean

acts_as_sender
optional

Whether or not this LegalEntity can act as a sender of documents.
Default : true

boolean

advertisements
optional

A list of document types to advertise. Use if this LegalEntity needs the ability to receive more than only invoice documents.

< enum (invoice, invoice_response, order, ordering, order_response, selfbilling) > array

city
required

The city.
Length : 2 - 64

string

country
required

Country

county
optional

County, if applicable
Maximal length : 64

string

line1
required

The first address line.
Length : 2 - 192

string

line2
optional

The second address line, if applicable
Maximal length : 192

string

party_name
required

The name of the company.
Length : 2 - 64

string

public
optional

Whether or not this LegalEntity is public. Public means it will be entered into the PEPPOL directory at https://directory.peppol.eu/
Default : true

boolean

rea
optional

The REA details for the LegalEntity. Only applies to IT LegalEntities.

Rea

tax_registered
optional

Whether or not this LegalEntity is tax registered. This influences the validation of the data presented when sending documents.
Default : true

boolean

tenant_id
optional

The id of the tenant, to be used in case of single-tenant solutions that share webhook URLs. This property will included in webhook events.
Maximal length : 64

string

third_party_password
optional

string

third_party_username
optional

string

zip
required

The zipcode.
Length : 2 - 32

string

6.2.50. LegalEntityUpdate

Name Description Schema

acts_as_receiver
optional

Whether or not this LegalEntity can act as a receiver of documents. If not, no identifiers will be provioned on any exchange network.
Default : true

boolean

acts_as_sender
optional

Whether or not this LegalEntity can act as a sender of documents.
Default : true

boolean

advertisements
optional

A list of document types to advertise. Use if this LegalEntity needs the ability to receive more than only invoice documents.

< enum (invoice, invoice_response, order, ordering, order_response, selfbilling) > array

city
optional

The city.
Length : 2 - 64

string

classification_code
optional

The classification code for this LegalEntity. For Malaysia, this is the MSIC code. It is mandatory for MY legal entities.

string

country
optional

Country

county
optional

County, if applicable
Maximal length : 64

string

id
optional

The Storecove assigned id for the LegalEntity.

integer (int64)

line1
optional

The first address line.
Length : 2 - 192

string

line2
optional

The second address line, if applicable
Maximal length : 192

string

party_name
optional

The name of the company.
Length : 2 - 64

string

public
optional

boolean

rea
optional

The REA details for the LegalEntity. Only applies to IT LegalEntities.

Rea

smart_inbox
optional

DEPRECATED. Use the ReceivedDocuments endpoint. The email address of the Smart Inbox for this LegalEntity.

string

tax_registered
optional

Whether or not this LegalEntity is tax registered. This influences the validation of the data presented when sending documents.
Default : true

boolean

tenant_id
optional

The id of the tenant, to be used in case of multi-tenant solutions. This property will included in webhook events.
Maximal length : 64

string

third_party_password
optional

string

third_party_username
optional

string

zip
optional

The zipcode.
Length : 2 - 32

string

6.2.51. LineAllowanceCharge

Name

Description

Schema

amountExcludingTax
required

The amount for the allowance or charge, excluding tax.

number

baseAmountExcludingTax
optional

The base amount for the allowance or charge, excluding tax.

number

reason
optional

The reason for the allowance or charge, free text

string

reasonCode
optional

DEPRECATED. Do not use. Contact Storecove first if you want to use this field.

string

6.2.52. LineDelivery

Name

Schema

deliveryLocation
optional

deliveryLocation

deliveryLocation

Name Description Schema

id
optional

The location identifier.
Minimum length : 2

string

requestedDeliveryPeriod
optional

The requested delivery period. If not present, will be taken from the document level. If that is not present, this field is mandatory.
Pattern : "^[0-9]{4}-[0-9]{2}-[0-9]{2} - [0-9]{4}-[0-9]{2}-[0-9]{2}$"

string

schemeId
optional

The schemeId of the location identifier (e.g. '0088')

string

6.2.53. NetworkSettings

Settings for an additional routing network.

Name Description Schema

mock
optional

Whether or not to mock the network, if possible.
Default : false

boolean

scheme
optional

Whether or not the network is enabled

boolean

6.2.54. OrderLine

Name Description Schema

accountingCost
optional

The buyer’s accounting cost centre for this line.
Minimum length : 1

string

additionalItemProperties
optional

An array of additional item properties.

< AdditionalItemProperty > array

allowPartialDelivery
optional

Whether or not the line items must be delivered in a single shipment.
Default : false

boolean

allowanceCharges
optional

An array of allowance charges.

< LineAllowanceCharge > array

amountExcludingTax
required

The amount excluding tax. Should equal quantity x itemPrice + allowanceCharge.

number

baseQuantity
optional

The number of items the price is for.

number

delivery
optional

The delivery information for the line.

LineDelivery

description
optional

The description for this line.
Length : 1 - 255

string

itemPrice
optional

The price per item (may be fractional)

number

lineId
required

The id for this invoice line.
Minimum length : 1

string

lotNumberIds
optional

An identifier for the production lot which the line items come from.

< string > array

name
optional

A short name for this line.
Length : 1 - 255

string

note
optional

A note to add to the line
Maximal length : 255

string

quantity
required

The number of items (may be fractional).

number

quantityUnitCode
required

The unit of measure that applies to the quantity. Codes for unit of packaging from UNECE Recommendation No. 21 can be used in accordance with the descriptions in the "Intro" section of UN/ECE Recommendation 20, Revision 11 (2015): The 2 character alphanumeric code values in UNECE Recommendation 21 shall be used. To avoid duplication with existing code values in UNECE Recommendation No. 20, each code value from UNECE Recommendation 21 shall be prefixed with an “X”, resulting in a 3 alphanumeric code when used as a unit of measure. Note that the following additionally allowed codes are deprecated and will be converted to C62: 04, 05, 08, 16, 17, 18, 19, 26, 29, 30, 31, 32, 36, 43, 44, 45, 46, 47, 48, 53, 54, 62, 63, 64, 66, 69, 71, 72, 73, 76, 78, 84, 90, 92, 93, 94, 95, 96, 97, 98, 1A, 1B, 1C, 1D, 1E, 1F, 1G, 1H, 1J, 1K, 1L, 1M, 1X, 2V, 2W, 3E, 3G, 3H, 3I, 4A, 4B, 4E, 5C, 5F, 5G, 5H, 5I, 5K, 5P, 5Q, A1, A25, A50, A51, A52, A57, A58, A60, A61, A62, A63, A64, A65, A66, A67, A77, A78, A79, A80, A81, A82, A83, AJ, AM, AP, AR, ARE, ATT, AV, AW, B0, B2, B36, B37, B38, B39, B40, B5, B51, B6, B65, B9, BD, BE, BG, BH, BJ, BK, BL, BO, BR, BT, BW, BX, BZ, C1, C2, C4, C5, C6, C77, C98, CA, CH, CJ, CK, CL, CO, CQ, CR, CS, CT, CU, CV, CY, CZ, D14, D28, D35, D37, D38, D39, D40, D64, D66, D67, D7, D70, D71, D72, D75, D76, D79, D8, D9, D90, D92, D96, D97, D98, D99, DC, DE, DI, DQ, DR, DRM, DS, DU, DX, DY, E2, E3, E5, EC, EP, EV, F1, F9, FB, FD, FE, FG, FM, G7, GC, GD, GH, GK, GN, GRT, GT, GW, GY, GZ, H1, H2, HAR, HD, HE, HF, HI, HJ, HK, HL, HN, HO, HP, HS, HT, HY, IC, IF, II, IL, IM, IP, IT, JB, JG, JO, JR, K5, KD, KF, KG, KS, KTM, LC, LE, LI, LJ, LX, M0, MA, MF, MK, MQ, MT, MV, N2, NB, NBB, NC, ND, NE, NG, NH, NI, NJ, NN, NPL, NPR, NQ, NR, NRL, NTT, NV, NY, OP, OZ, P0, P3, P4, P6, P7, P8, P9, PA, PB, PE, PF, PG, PK, PL, PM, PN, PT, PU, PV, PW, PY, PZ, QD, QH, QK, QT, R4, RA, RD, RG, RK, RL, RN, RO, RS, RU, S5, S6, S7, S8, SA, SD, SE, SHT, SK, SL, SN, SO, SP, SS, SST, ST, SV, T1, T4, T5, T6, T7, T8, TA, TC, TD, TE, TF, TJ, TK, TL, TN, TQ, TR, TS, TSD, TSH, TT, TU, TV, TW, TY, UA, UD, UE, UF, UH, UM, VI, VQ, VS, W4, WH, WI, WR, WW, YL, YT, Z1, Z2, Z3, Z4, Z5, Z6, Z8
Default : "C62"

references
optional

< Reference > array

taxesDutiesFees
optional

< Tax > array

6.2.55. OriginatorCustomerParty

The originator of the document.

Name

Schema

party
required

Party

6.2.56. OriginatorParty

The originator of the line.

Name

Description

Schema

party
required

object

publicIdentifiers
optional

A list of legal and tax identifiers for the originator party.

< PublicIdentifier > array

6.2.57. Party

A party that can receive or send invoices

Name Description Schema

address
optional

Address

classificationCode
optional

The classification code of the company transporting the invoice. This currently is used only for the Malaysia LHDNM application in selfBillingMode. In that case, it becomes the MSIC of the sender of the purchase invoice.
Pattern : "^[0-9]{5}$"

string

companyName
optional

The name of the company transporting the invoice
Minimum length : 2

string

contact
optional

Contact

registrationName
optional

The registration name of the company transporting the invoice

string

6.2.58. PaymentMeans

A PaymentMeans is a way to pay the invoice.

Name

Description

Schema

account
optional

The account number.

string

amount
optional

The amount to be paid for this category. Only used for Dutch G-Account invoices. The amount nl_ga_beneficiary + amount nl_ga_gaccount must add up to the amountExcludingVat

number

branche_code
optional

The bank branch code. Not required for IBAN numbers. Often referred to as Swift or Bic code.

string

code
required

How the invoice has been / will be paid. The code determines which type of PaymentMeans is used and which fields are mandatory.

cash
The invoice was/is paid in cash.
bank_cheque
The invoice was/is paid via a bank cheque.
cashiers_cheque
The invoice was/is paid via a cashiers cheque.
credit_transfer, sepa_credit_transfer
The amount is to be transfered into a bank account. Relevant additional fields:
- account
  The account number. For New Zealand, this should hold the full 16 digit bank account number. Mandatory.
- branche_code
  In case of an IBAN, the account alone number is sufficient. In other cases, like a BBAN, a BIC code or other additional identifier is required. For Australia, the BSB goes here. Optional.
- holder
  The account holder name. Optional.
Note that using 'sepa_credit_transfer' will result in the PaymentMeansCode of '58' being used in UBL documents. Otherwise, the more generic '30' will be used.
debit_transfer
Used for CreditNotes. The amount is to be transfered by the sender of the document into the bank account of the receiver of the document. Relevant additional fields:
- account
  The account number. For New Zealand, this should hold the full 16 digit bank account number. Mandatory.
- branche_code
  In case of an IBAN, the account alone number is sufficient. In other cases, like a BBAN, a BIC code or other additional identifier is required. For Australia, the BSB goes here. Optional.
direct_debit, sepa_direct_debit
Direct debit. Relevant additional fields:
- account
  The account number from which the funds will be debited. Mandatory.
- mandate
  The direct debit mandate id. Mandatory.
- holder
  The account holder name. Optional.
Note that using 'sepa_direct_debit' will result in the PaymentMeansCode of '59' being used in UBL documents. Otherwise, the more generic '49' will be used.
card, credit_card, bank_card (credit_card, bank_card are deprecated)
E.g. credit or debit card. Relevant additional fields:
- account
  The card number, but never more than the last four digits. Mandatory.
- holder
  The account holder name. Optional.
- network
  The payment network, e.g. VISA, SEPA. Optional, but recommended since a default of "N/A" may be used if not provided.
online_payment_service
An online payment service has been or will be used. Relevant additional fields:
- network
  The payment network, e.g. PayPal. Mandatory unless url is provided.
- url
  The URL to execute the payment. Mandatory unless network is provided.
It is possible to provide both url and network. Note that for UBL, in countries where this payment means is not allowed, this will translate into an AdditionalDocumentReference.Attachment.ExternalReference element.
standing_agreement
The payment means has been agreed out of band. Relevant additional fields: none.
aunz_npp_payid, aunz_npp (aunz_npp is deprecated)
Australia/New Zealand New Payments Platform. Relevant additional fields:
- account
  PayID. May be an email address, ABN, mobile phone number etc. Mandatory.
aunz_npp_payto
Australia/New Zealand New Payments Platform. Relevant additional fields:
- account
  Account number. Mandatory.
- mandate
  Mandate/direct debit authority reference/PayTo Agreement. Mandatory.
aunz_bpay
Australia/New Zealand New Payments Platform. Relevant additional fields:
- account
  Biller code. Mandatory.
- holder
  The account holder name. Optional.
aunz_postbillpay
Australia/New Zealand New Payments Platform. Relevant additional fields:
- account
  Biller code. Mandatory..
- holder
  The account holder name. Optional.
aunz_uri
Australia/New Zealand URI. Relevant additional fields:
- account
  Payment URI. Mandatory..
- holder
  The account holder name. Optional.
se_bankgiro
Swedish Bankgiro. Relevant additional fields:
- account
  The account number from which the funds will be debited, 7 or 8 digits. Mandatory.
- holder
  The account holder name. Optional.
se_plusgiro
Swedish Plusgiro. Relevant additional fields:
- account
  The account number from which the funds will be debited, 2 - 8 digits. Mandatory.
- holder
  The account holder name. Optional.
sg_giro
Singapore GIRO-system (direct debit). Relevant additional fields: none.
sg_card
Singapore CreditCard payment. Relevant additional fields: none.
sg_paynow
Singapore PayNow Corporate. Relevant additional fields:
- account
  The UEN, format: UENxxxxxxxxxx. Mandatory.
it_mav
Italy MAV payment.
it_pagopa
Italy PagoPA payment.

enum (credit_transfer, sepa_credit_transfer, debit_transfer, direct_debit, sepa_direct_debit, card, bank_card, credit_card, online_payment_service, cash, bank_cheque, cashiers_cheque, standing_agreement, aunz_npp, aunz_npp_payid, aunz_npp_payto, aunz_bpay, aunz_postbillpay, aunz_uri, se_bankgiro, se_plusgiro, sg_giro, sg_card, sg_paynow, it_mav, it_pagopa, nl_ga_beneficiary, nl_ga_gaccount, undefined)

holder
optional

The name of the account holder.

string

mandate
optional

The direct debit mandate code.

string

network
optional

The name of the card network, e.g. VISA.

string

paymentId
optional

The payment id that you will use to match the payment against the invoice.

string

6.2.59. PaymentTerms

The payment terms of the document.

Name

Description

Schema

note
optional

The note for the payment terms.

string

6.2.60. PeppolIdentifier

Name Description Schema

corppass
optional

CorpPass details, if applicable.

CorpPass

identifier
optional

The identifier.
Length : 2 - 64

string

scheme
optional

The scheme of the identifier. See Receiver Identifiers for a list.
Length : 2 - 64

string

superscheme
optional

The superscheme of the identifier. Should always be "iso6523-actorid-upis".
Length : 2 - 64

string

6.2.61. PeppolIdentifierCreate

Name Description Schema

corppass
optional

CorpPass details, used to create SG:UEN (numerical code: 0195) identifiers. For details, see SG - Singapore.

CorpPassCreate

identifier
required

The identifier.
Length : 2 - 64

string

networks
optional

The networks to advertise the identifier on. Note that "dbna" currently requires manual provisioning in the DBNA SML, so you need to contact us before using this.

< enum (peppol, dbna, fr_dctce_poc) > array

scheme
required

The scheme of the identifier. See Receiver Identifiers for a list.
Length : 2 - 64

string

superscheme
required

The superscheme of the identifier. Should always be "iso6523-actorid-upis".
Length : 2 - 64

string

6.2.62. PreflightInvoiceRecipientResult

The result of preflighting an invoice recipient

Name

Description

Schema

code
optional

The result code of the preflight request

enum (ok, nok)

6.2.63. PublicIdentifier

A public identifier for this customer.

Name Description Schema

id
required

The actual identifier.
Minimum length : 1

string

scheme
required

The scheme of the identifier. See Receiver Identifiers for a list.
Minimum length : 3

string

6.2.64. PublicIdentifiers

A list of public identifiers that uniquely identify this customer.

Type : < PublicIdentifier > array

6.2.65. PurchaseInvoice

Name

Description

Schema

accounting
optional

DEPRECATED - The accounting details for the invoice. Will only evern contain null properties.

PurchaseInvoiceAccountingDetails

accounting_cost
optional

The accounting cost code.

string

allowance_charge
optional

DEPRECATED - Use the allowance_charges array.

number

allowance_charges
optional

< PurchaseInvoiceAllowanceCharge > array

amount_including_vat
optional

DEPRECATED - Use amount_including_tax.

number

attachments
optional

< PurchaseInvoiceAttachment > array

billing_reference
optional

Reference to the previous invoice this invoice relates to.

string

buyer_reference
optional

Reference provided by the buyer. Used for routing.

string

contract_document_reference
optional

Reference to the contract.

string

delivery
optional

The details of the delivery associated with this invoice.

PurchaseInvoice Delivery

document
optional

DEPRECATED. Use the new atatchments array.

string

document_currency_code
optional

The ISO 4217 currency for the invoice.

string

document_totals
optional

The total amounts for this document.

PurchaseInvoiceDocumentTotals

document_type
optional

The type of document. Only "invoice" for now.

enum (invoice)

due_date
optional

The date the invoice must be payed by. Format "YYYY-MM-DD".

string

external_key
optional

Deprecated. Used for accountants. The id you specified for the organization.

string

external_user_id
optional

Deprecated. Used for the embedded portal retrieval service. The external_user_id you provided when the ShopAccount was created.

string

guid
optional

The GUID of the invoice

string (uuid)

invoice_lines
optional

< PurchaseInvoiceInvoiceLine > array

invoice_number
optional

The invoicenumber.

string

invoice_type
optional

The type of invoice.

enum (invoice, creditnote, correctioninvoice)

issue_date
optional

The date the invoice was issued. Format "YYYY-MM-DD".

string

legal_entity_id
optional

The id of the LegalEntity the invoice was received for.

integer (int64)

note
optional

The invoice level note.

string

order_reference
optional

Reference to the order. Used for matching the invoice to an order.

string

payment_means
optional

DEPRECATED - Use the new payment_means_array array.

Payment Means - DEPRECATED

payment_means_array
optional

The different payment means that can be used to pay the invoice.

< PurchaseInvoicePaymentMeans > array

payment_means_payment_id
optional

DEPRECATED - use the payment_id property in the payment_means_array

string

payment_terms_note
optional

A textual description of the payment terms.

string

period_end
optional

The end date of the period this invoice relates to. Format "YYYY-MM-DD".

string

period_start
optional

The start date of the period this invoice relates to. Format "YYYY-MM-DD".

string

project_reference
optional

Reference to the project.

string

sender
optional

The organzation that sent the invoice.

PurchaseInvoiceSender

source
optional

The source the invoice was received from.

enum (peppol, script, supplier, email)

sub_type
optional

The subtype of document.

enum (invoice, creditnote, correctioninvoice)

system_generated_primary_image
optional

Whether or not the document image (PDF) was generated by Storecove. If true, it means the invoice was received without any attachments and Storecove generated one for you. If false, the invoice will contain at least one attachment, which was received from the invoice sender.

boolean

tax_point_date
optional

The date the invoice was issued for tax purposes. In most countries MUST match the issue_date. Format "YYYY-MM-DD".

string

tax_subtotals
optional

< PurchaseInvoiceTaxSubtotal > array

tax_system
optional

The tax system of the invoice. Either tax_line_percentages or tax_line_amounts. The first tax system means the invoice lines contain only the tax percentages and the tax amounts are included only in the tax subtotals at the invoice level and so are only calculated at the invoice level. The tax system tax_line_amounts means that in addition to the percentage, each invoice line also contains the tax amount. The tax subtotals at the invoice level are calculated as the sum of the tax of the invoice lines. The distinction between the two tax systems has has implications for rounding.

string

vat_reverse_charge
optional

DEPRECATED - This is now part of each invoice line.

boolean

PurchaseInvoice Delivery

Name

Description

Schema

actual_date
optional

The actual delivery date.

string

location
optional

The location the goods/services were delivered to.

Location

party
optional

The party the goods/services were delivered to.

PurchaseInvoice Party

Location

Name

Description

Schema

building_number
optional

The building number. Used in SA.

string

city
optional

Address city.

string

country
optional

Address country.

string

county
optional

Address county.

string

department
optional

Department name.

string

id
optional

The id of the location.

string

line1
optional

Address line 1.

string

line2
optional

Address line 2.

string

neighborhood
optional

The neighborhood. Used in SA.

string

scheme_id
optional

The scheme id for the id of the location.

string

secondary_number
optional

The secondary number. Used in SA.

string

zip
optional

Address zip code

string

PurchaseInvoice Party

Name

Description

Schema

name
optional

The name of the deliveyr party.

string

Payment Means - DEPRECATED

Name

Description

Schema

iban
optional

The IBAN to which to transfer.

string

id
optional

An id to mention in the transfer.

string

6.2.66. PurchaseInvoiceAccountingDetails

Name

Description

Schema

code
optional

The the code of the general ledger account.

string

list
optional

The name of the list for the code, e.g. "RGS".

string

list_version
optional

The version of the list for the code, e.g. "1.1".

string

name
optional

A textual description of the code.

string

6.2.67. PurchaseInvoiceAllowanceCharge

Name

Description

Schema

amount_excluding_tax
optional

The amount excluding tax.

number

amount_excluding_vat
optional

DEPRECATED - use amount_excluding_tax.

string

reason
optional

The reason for the allowance or charge.

string

tax
optional

PurchaseInvoiceTax

vat
optional

DEPRECATED.

PurchaseInvoiceVat

6.2.68. PurchaseInvoiceAttachment

Name

Description

Schema

content_type
optional

The attachment content type (mime type).

string

document
optional

The Base64 encoded document attachment.

string

6.2.69. PurchaseInvoiceDocumentTotals

Name

Description

Schema

payable
optional

The total invoice amount payable including tax.

number

prepaid
optional

The amount already paid.

number

rounding
optional

The difference between the payable amount and the total invoice amount including tax.

number

total
optional

The total invoice amount, including tax. This is equal to the sum of the invoice_lines (amount_excluding_tax + tax.amount) and the allowances and charges.

number

6.2.70. PurchaseInvoiceInvoiceLine

Name

Description

Schema

accounting
optional

The accounting details for the invoice line.

PurchaseInvoiceAccountingDetails

allowance_charge
optional

DEPRECATED - use allowance_charges.

number

allowance_charge_array
optional

< PurchaseInvoiceInvoiceLineAllowanceCharge > array

allowance_charges
optional

Deprecated.

< number > array

amount_excluding_tax
optional

The amount excluding Tax. This is equal to quantity x price_amount + ∑ allowance_charges.

number

amount_excluding_vat
optional

DEPRECATED - use amount_excluding_tax. The amount excluding VAT.

number

description
optional

The description for the invoice line.

string

name
optional

A short name for the invoice line.

string

period_end
optional

The end date of the period this invoice line relates to. Format "YYYY-MM-DD".

string

period_start
optional

The start date of the period this invoice line relates to. Format "YYYY-MM-DD".

string

price
optional

The price for one item, excluding VAT.

PurchaseInvoiceInvoiceLinePrice

tax
optional

The tax details for the invoice line.

PurchaseInvoiceTax

units
optional

The number of items

PurchaseInvoiceInvoiceLineItem

vat
optional

DEPRECATED - use tax. The VAT details for the invoice line.

VAT Details

VAT Details

Name

Description

Schema

amount
optional

The amount of VAT for the invoice line.

number

country
optional

The ISO 3166 country of the VAT for the invoice line.

string

percentage
optional

The percentage of VAT for the invoice line.

number

6.2.71. PurchaseInvoiceInvoiceLineAllowanceCharge

Name

Description

Schema

amount
optional

The amount of the allowance or charge.

number

reason
optional

The reason for the allowance or charge.

string

6.2.72. PurchaseInvoiceInvoiceLineItem

Name

Description

Schema

quantity
optional

The quantity of the item. Can have up to digits.

number

unit_code
optional

The unit code of the quantity.

string

6.2.73. PurchaseInvoiceInvoiceLinePrice

Name

Description

Schema

base_quantity
optional

The number of items the price is for. Can have up to digits.

number

price_amount
optional

The price for one item, excluding VAT. Can have up to digits.

number

6.2.74. PurchaseInvoicePaymentMeans

Name

Description

Schema

account
optional

The account number to which to transfer.

string

branch_code
optional

The code identifying the bank branch. May contain a BIC/SWIFT or something appropriate for the payment method, such as "NPP" for type NppPaymentMean.

string

holder
optional

The account holder name to which to transfer.

string

mandate
optional

The mandate, used only for type DirectDebitPaymentMean.

string

network
optional

The payment network. Used only for type CardPaymentType.

string

payment_id
optional

The payment id to use when making the payment. The invoice sender will use this to match the received funds to the invoice.

string

type
optional

The type of payment means. Which type are returned is determined by the &pmv= query parameter. For details see documentation for that field.

enum (BankPaymentMean, DirectDebitPaymentMean, CardPaymentMean, NppPaymentMean, SeBankGiroPaymentMean, SePlusgiroPaymentMean, SgCardPaymentMean, SgGiroPaymentMean, SgPaynowPaymentMean, CreditTransferPaymentMean, CreditCardPaymentMean, SeBankgiroPaymentMean, AunzNppPayidPaymentMean, OnlinePaymentServicePaymentMean, StandingAgreementPaymentMean, AunzNppPaytoPaymentMean, AunzBpayPaymentMean, AunzPostbillpayPaymentMean, AunzUriPaymentMean)

6.2.75. PurchaseInvoiceSender

Name

Description

Schema

billing_contact
optional

The billing contact for the invoice.

PurchaseInvoiceSenderBillingContact

building_number
optional

The building number. Used in SA.

string

city
optional

The city.

string

country
optional

The country.

string

county
optional

The county.

string

department
optional

The department who sent the invoice.

string

identifiers
optional

The array of identifiers for this sender.

< PeppolIdentifier > array

legal_name
optional

The legal name of the party who sent the invoice.

string

line1
optional

The address

string

line2
optional

The address, line 2

string

neighborhood
optional

The neighborhood. Used in SA.

string

party_name
optional

The party who sent the invoice.

string

peppol_identifiers
optional

DEPRECATED - Use the identifiers array.

PeppolIdentifier

secondary_number
optional

The secondary number. Used in SA.

string

zip
optional

The zip code.

string

6.2.76. PurchaseInvoiceSenderBillingContact

Name

Description

Schema

email
optional

The email of the billing contact.

string

first_name
optional

The first name of the billing contact.

string

last_name
optional

The last name of the billing contact.

string

6.2.77. PurchaseInvoiceTax

Name

Description

Schema

tax
optional

The tax element.

PurchaseInvoiceTaxElement

PurchaseInvoiceTaxElement

Name

Description

Schema

amount
optional

The tax amount.

number

category
optional

The tax category.

enum (standard, zero_rated, reverse_charge, intra_community, exempt, export, outside_scope, regulation33_exempt, nonregulation33_exempt, deemed_supply, srca_s, srca_c, not_registered, igst, cgst, sgst, cess, state_cess, srovr, srovr_rs, srovr_lvg, srlvg, sales, service, tourism, high_value_goods, low_value_goods)

category_code
optional

Deprecated. The tax category code.

string

country
optional

The tax country.

string

percentage
optional

The tax percentage.

number

type
optional

The tax type.

enum (VAT, GST)

6.2.78. PurchaseInvoiceTaxSubtotal

Name

Description

Schema

amount_excluding_tax
optional

The amount excluding tax.

number

amount_excluding_vat
optional

DEPRECATED - use amount_excluding_tax.

string

tax
optional

PurchaseInvoiceTax

vat
optional

DEPRECATED.

PurchaseInvoiceVat

6.2.79. PurchaseInvoiceUbl

Name

Description

Schema

external_key
optional

Used for accountants. The id you specified for the organization.

string

external_user_id
optional

Used for the embedded portal retrieval service. The external_user_id you provided when the ShopAccount was created.

string

guid
optional

The GUID of the invoice

string (uuid)

legal_entity_id
optional

The id of the LegalEntity the invoice was received for.

integer (int64)

system_generated_primary_image
optional

boolean

tax_system
optional

string

ubl
optional

The Base64 encoded UBL invoice.

string

6.2.80. PurchaseInvoiceVat

DEPRECATED - Use tax.

Name

Description

Schema

amount
optional

The VAT country.

string

percentage
optional

The VAT percentage.

string

6.2.81. RawDocumentData

A document to send, in base64 encoded format.

Name Description Schema

document
required

The base64 encoded version of the document.
Minimum length : 5

string

documentTypeId
optional

DEPRECATED. The document type id of the document. Required when parse == false.

string

parse
optional

If true, the data will be extracted from the document and used to create the JSON that is used in our API. Only parse == true is currently supported.
Default : true

boolean

parseStrategy
optional

How to parse the document. Only needed when parse == true.

enum (ubl, cii, idoc, setu14)

processId
optional

DEPRECATED. The process id of the document. Required when parse == false.

string

6.2.82. Rea

Name Description Schema

capital
optional

The captial for the company.

number

identifier
optional

The identifier.
Length : 2 - 20

string

liquidation_status
optional

The liquidation status of the company.

enum (LN, LS)

partners
optional

The number of partners.

enum (SU, SM)

province
optional

The provincia of the ufficio that issued the identifier.

enum (AG, AL, AN, AO, AQ, AR, AP, AT, AV, BA, BT, BL, BN, BG, BI, BO, BZ, BS, BR, CA, CL, CB, CI, CE, CT, CZ, CH, CO, CS, CR, KR, CN, EN, FM, FE, FI, FG, FC, FR, GE, GO, GR, IM, IS, SP, LT, LE, LC, LI, LO, LU, MC, MN, MS, MT, VS, ME, MI, MO, MB, NA, NO, NU, OG, OT, OR, PD, PA, PR, PV, PG, PU, PE, PC, PI, PT, PN, PZ, PO, RG, RA, RC, RE, RI, RN, RO, SA, SS, SV, SI, SR, SO, TA, TE, TR, TO, TP, TN, TV, TS, UD, VA, VE, VB, VC, VR, VV, VI, VT)

6.2.83. ReceivableDocument

The received document.

Name

Description

Schema

documentType
required

The type of document received.

enum (invoice, order)

invoice
optional

An invoice or creditnote.

Invoice

order
optional

An order.

DocumentOrder

source
required

The source of the document.

enum (self, peppol, dbnalliance, ro-anaf, finvoice, it-sdi)

6.2.84. ReceivedDocument

Name

Description

Schema

guid
optional

The GUID of the received document

string (uuid)

6.2.85. ReceivedDocumentCreate

Name

Description

Schema

document
required

The Base64 encoded document.

string

parseStrategy
required

The attachment content type (mime type).

enum (rfc822)

6.2.86. ReceiverParty

Name Description Schema

address
optional

Address

classificationCode
optional

string

companyName
optional

The name of the company transporting the invoice
Minimum length : 2

string

contact
optional

Contact

registrationName
optional

The registration name of the company transporting the invoice

string

6.2.87. Reference

A reference to a document.

Name Description Schema

documentDescription
optional

A description for the referenced document.
Length : 2 - 1024

string

documentId
optional

The id of the referenced document.

string

documentIdListAgencyId
optional

The agency id of the list id of the id of the referenced document.

string

documentIdListId
optional

The list id of the id of the referenced document.

string

documentIdListVersionId
optional

The version id of the list id of the id of the referenced document.

string

documentIdSchemeAgencyId
optional

The the agency id of the scheme id of the id of the referenced document.

string

documentIdSchemeId
optional

The scheme id of the id of the referenced document.

string

documentIdSchemeVersionId
optional

The version id of the scheme id of the id of the referenced document.

string

documentType
required

The type of the referenced document. The following types are supported:

purchase_order (document level, Invoice)
A reference to an order for this document, assigned by the buyer. Note that this often is a key field, since many receivers of invoices will use this field to automatically match the invoice to an order they placed. Many receivers refuse invoices that cannot be automatically matched, in particular government agencies. So it is highly recommended to fill this field whenever possible.
billing (document level, Invoice)
A reference to a billing document. For instance, credit notes may refer to an invoice they are a credit note for.
billing_uuid (document level, Invoice)
DEPRECATED. Use the billingUuid property of the 'billing' reference. A UUID reference to a billing document. For instance, credit notes may refer to an invoice they are a credit note for.
sales_order (document level, Invoice + Order)
A reference to an order for this document, assigned by the seller.
buyer_reference (document level, Invoice, Order)
The buyer's reference. Used for internal routing by the receiver. For orders, this becomes the customer reference which the receiver of the order should put back in the buyer reference field in the invoice.
additional (document level, Invoice, Order)
An additional reference. For UBL, this translates into an AdditionalDocumentReference without a EmbeddedDocumentBinaryObject. For the latter, use the attachments array.
contract (document level, Invoice + Order)
A reference to a contract or framework agreement that this document relates to.
despatch_advice (document level, Invoice)
A reference to a despatch advice for this document. In the FatturaPA, this is what will become the DDT.
originator (document level, Invoice + Order)
A reference to an originator document for this invoice.
receipt (document level, Invoice)
A reference to a receipt document for this document.
project (document level, Invoice)
A reference to a project document for this document.
quotation (document level, Order)
A reference to a quotation document for this document.
replaced_order (document level, Order)
A reference to the initial order that was rejected and a new order is issued.
payment_url (document level, Invoice)
A to a payment URL for the invoice.
item_classification_code (line level)
A reference to a commodity classification / item classification code for this line. Note that in combination with the documentIdListId these can be used for Malaysia LHDNM to provide the product classification code (documentIdListId=CLASS) and the product tariff code (documentIdListId=PTC)
item_commodity_code (line level)
A reference to a commodity classification / commodity code for this line.
item_specification (line level)
A referece to an item specification document
line_document_reference (line level)
A reference to another document for this line.
line_standard_item_identification (line level)
A standard item identification.
line_sellers_item_identification (line level)
The seller's item identification.
line_buyers_item_identification (line level)
The buyer's item identification.
line_purchase_order (line level)
A reference to an order for this line, assigned by the buyer. Note not all outgoing document formats support this, so they may end up concatenated at the invoice level.

enum (purchase_order, replaced_order, buyer_reference, billing, billing_uuid, sales_order, contract, despatch_advice, originator, receipt, project, quotation, payment_url, additional, certified_exporter_authorization, free_trade_agreement, my_customs_form_1_9, my_customs_form_2, item_classification_code, item_commodity_code, item_specification, line_document_reference, line_standard_item_identification, line_sellers_item_identification, line_buyers_item_identification, line_purchase_order)

documentTypeCode
optional

The code of the referenced document type. Only used for documentType = 'line_document_reference'.
Pattern : "^uncl1001_[0-9]{1,3}$"

string

documentUuid
optional

The UUID of the referenced document.

string

issueDate
optional

The issue date of the referenced document.
Pattern : "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"

string

lineId
optional

The line in the referenced document.

string

6.2.88. Routing

The different ways to send the invoice to the recipient. The publicIdentifiers are used to send via the Peppol network, if the recipient is not registered on the Peppol network, the invoice will be sent to the email addresses in the emails property. This property is only mandatory when sending the invoice data using the Invoice property, not when sending using the InvoiceData property, in which case this information will be extracted from the InvoiceData object. If you do specify an InvoiceRecipient object and an InvoiceData object, the data from the two will be merged.

Name Description Schema

clearWithoutSending
optional

If you wish to send the document yourself in a Y-flow, use this flag. Wait for the 'cleared' webhook and use the Get DocumentSubmission Evidence endpoint to retrieve the clearing evidence. This will include a sendable document.
Default : false

boolean

eIdentifiers
optional

The electronic identifiers for this invoice recipient. These are the identifiers used on the Peppol network.

EIdentifiers

emails
optional

The email addresses the invoice should be sent to if none of the other identifiers can be used

< string (email) > array

networks
optional

Any additional networks to consider for routing

< RoutingNetwork > array

6.2.89. RoutingIdentifier

An electronic routing identifier.

Name Description Schema

id
required

The actual identifier.
Minimum length : 1

string

role
optional

The role of the identifier. Only used for B2G sending to ES.

enum (es_01_fiscal, es_02_receptor, es_03_pagador)

scheme
required

The scheme of the identifier. See Receiver Identifiers for a list.
Minimum length : 3

string

6.2.90. RoutingNetwork

An additional network to consider for routing.

Name Description Schema

scheme
optional

The name of the network
Minimum length : 3

string

settings
required

The settings for the network.

NetworkSettings

6.2.91. SellerSupplierParty

The party sending the order.

Name

Description

Schema

party
required

SenderParty

publicIdentifiers
required

A list of legal and tax identifiers for this customer.

< PublicIdentifier > array

6.2.92. SendableDocument

The document to send.

Name

Description

Schema

documentType
required

The type of document to be sent.

enum (invoice, invoice_response, order)

invoice
optional

An invoice or creditnote.

Invoice

invoiceResponse
optional

An invoice response.

DocumentInvoiceResponse

order
optional

An order..

DocumentOrder

rawDocumentData
optional

RawDocumentData

6.2.93. SenderParty

A party that can send documents

Name

Schema

contact
optional

Contact

6.2.94. Shipment

Name Description Schema

allowanceCharges
optional

A list of charges

< AllowanceCharge > array

originAddress
optional

The address from which the shipment is being sent. Currently supports country only.

Address

shippingMarks
optional

A text that the buyer requests to be printed on the packing labels. Used only for DocumentOrder.
Maximal length : 128

string

6.2.95. Tax

Name

Description

Schema

amount
optional

The amount of tax. Mandatory if taxSystem == 'tax_line_amounts'. However, it is best to use taxSystem tax_line_percentages and provide only the percentage, not the actual amount. The amount is then provided at the invoice level, in the taxSubtotals element.

number

category
optional

The allowed values depend on the country of the tax:

AU:
- standard (10%, 5.5%)
- zero_rated (0%)
- export (0%)
- exempt (0%)
- outside_scope (0%)
EU:
- standard (percentages country dependent)
- zero_rated (0%)
- reverse_charge (0%)
- intra_community (0%)
- export (0%)
- exempt (0%)
- outside_scope (0%)
EU/IT:
- standard
- zero_rated (0%)
- reverse_charge (0%)
- intra_community (0%)
- export (0%)
- exempt (0%)
- outside_scope (0%)
- bollo_virtuale (only at the invoice level and with mandatory amount: €2.00)
IN:
- igst (28%, 18%, 12%, 5%, 3%, 0.25%)
- sgst (14%, 9%, 6%, 2.5%, 1.5%
- cgst (14%, 9%, 6%, 2.5%, 1.5%
- cess (any percentage)
- state_cess (any percentage)
- reverse_charge (0%)
- export (0%)
- exempt (0%)
- outside_scope (0%)
- zero_rated (0%)
JP:
- standard (10%, 8%)
- export (0%)
- exempt (0%)
- outside_scope (0%)
MY:
- sales (5%, 10%) ⮕ LHDNM "01", Peppol "T"
- sales_zero (0%) ⮕ LHDNM "01", Peppol "E"
- service (6%, 8%) ⮕ LHDNM "02", Peppol "T"
- service_zero (0%) ⮕ LHDNM "02", Peppol "E"
- tourism (any amount) ⮕ LHDNM "03", Peppol "T"
- high_value_goods (any percentage) ⮕ LHDNM "04", Peppol "T"
- low_value_goods (10%) ⮕ LHDNM "05", Peppol "T"
- zero_rated (0%) ⮕ LHDNM "06", Peppol "E"
- export (0%) ⮕ LHDNM "E", Peppol "E"
- exempt (0%) ⮕ LHDNM "E", Peppol "E"
- outside_scope (0%) ⮕ LHDNM "06", Peppol "O"
NZ:
- standard (15%)
- zero_rated (0%)
- export (0%)
- exempt (0%)
- outside_scope (0%)
SG:
- standard (7%; 8% from 2023-01-01; 9% from 2024-01-01)
- deemed_supply (7%; 8% from 2023-01-01; 9% from 2024-01-01)
- srca_c (7%; 8% from 2023-01-01; 9% from 2024-01-01)
- srovr (7%; NOT to be used from 2023-01-01)
- srovr_rs (8% from 2023-01-01; 9% from 2024-01-01)
- srovr_lvg (8% from 2023-01-01; 9% from 2024-01-01)
- srlvg (8% from 2023-01-01; 9% from 2024-01-01)
- srca_s (0%)
- outside_scope (0%)
- not_registered (0%)
- zero_rated (0%)
- regulation33_exempt (0%)
- nonregulation33_exempt (0%)
- export (0%)
US:
- standard (any percentage)
- export (0%)
- exempt (0%)
- outside_scope (0%)

enum (standard, zero_rated, reverse_charge, intra_community, exempt, export, outside_scope, regulation33_exempt, nonregulation33_exempt, deemed_supply, srca_s, srca_c, not_registered, igst, cgst, sgst, cess, state_cess, srovr, srovr_rs, srovr_lvg, srlvg, bollo_virtuale, exempt_it_n1, sales, service, tourism, high_value_goods, low_value_goods, sales_zero, service_zero)

country
required

Country

percentage
optional

The percentage Tax. This should be a valid Tax percentage in the country at the time of the issueDate of this invoice. Mandatory if taxSystem == 'tax_line_percentages'

number

type
optional

The type of tax. This field is only used for receiving. For sending, the type is automatically determined from the country code and should not be supplied.

enum (VAT, GST)

6.2.96. TaxSubtotal

The total amount of tax of this type in the invoice.

Name

Description

Schema

category
optional

The tax category. For a description see Tax

enum (standard, zero_rated, reverse_charge, intra_community, exempt, export, outside_scope, regulation33_exempt, nonregulation33_exempt, deemed_supply, srca_s, srca_c, not_registered, igst, cgst, sgst, cess, state_cess, srovr, srovr_rs, srovr_lvg, srlvg, bollo_virtuale, exempt_it_n1, sales, service, tourism, high_value_goods, low_value_goods, sales_zero, service_zero)

country
required

The country levying the tax.

Country

percentage
optional

The tax percentage. This should be a valid tax percentage in the country at the time of the taxpointDate of this invoice.

number

taxAmount
required

The amount of tax.

number

taxableAmount
optional

The amount on which the tax is levied.

number

6.2.97. Transportable

A transportable document. Currently only used for receiving.

Name

Description

Schema

direction
optional

The direction of the document.

enum (in, out)

document
optional

The parsed received document. Not present if the original was requested.

ReceivableDocument

guid
optional

The GUID of the document that was received

string

legalEntityId
optional

The id of the LegalEntity this document should be sent on behalf of or was received for.

integer

original
optional

The document as originally received. Process this as a blob. Only present if requested.

string

6.2.98. WebhookInstance

Name

Description

Schema

body
optional

The webhook body that would have been pushed if this were a push-mode webhook.

string

guid
optional

The GUID of the WebhookInstance. Use this to delete it.

string (uuid)

7. Appendix

7.1. Countries

The API is is generic as possible. However, some countries have specific requirements or features that are listed here.

7.1.1. AT - Austria

When sending invoices to the Austrian government (AT:GOV), all invoices have to be routed to AT:GOV b (for production) or AT:GOV test (for test). The actual recipient will be determined from the order reference inside the document and the sender is identified by a custom identifier that must be included on the accountingSupplierParty. So the JSON will look something like

{
  "routing":{
    "publicIdentifiers":[
      {
        "scheme":"AT:GOV",
        "id":"b"
      }
    ]
  },
  "document":{
    "documentType":"invoice",
    "invoice":{
      "x2y": "b2g",
      "references":[
        {
          "documentType":"purchase_order",
          "documentId":"XXX",
        }
      ],
      "accountingSupplierParty":{
        "customerAssignedAccountIdValue":"12345678",
      }
    }
  }
}

Invoices to companies (AT:KUR / 9919) are routed directly to that identifier.

7.1.2. AU - Australia

Multiple PaymentMeans in the PaymentMeansArray are only allowed if they are of the same type.

You cannot send to yourself.

7.1.3. BE - Belgium

Belgium has the Hermes system. This means all BE:EN numbers are registered on the Peppol network. When you create a new LegalEntity for a BE:EN number, this is automatically and transparantly transferred from Hermes to Storecove.

7.1.4. CH - Switzerland

For Swiss receivers we support QRBill. For this to work, the following conditions apply:

You must provide a PDF (in the Attachment array). The QRBill will be added as an additional page.
The LegalEntity or the invoice (paymentMeansArray) must have a "credit_transfer" payment means.
The paymentId for the payment means must be a valid QR Reference (26 numeric characters followed by a check digit) or a valid Creditor Reference (ISO 11649).
The account for the payment means must be a valid IBAN starting with "CH".
- If the paymentId is a QR Reference, the IBAN must be a QR-IBAN, meaning an IBAN from "CHnn 3100 0nnn nnnn nnnn n" to "CHnn 3199 9nnn nnnn nnnn n".
- If the paymentId is a Creditor Reference, the IBAN must be a regular IBAN.

7.1.5. DE - Germany

The invoice.accountingSupplierParty.party.contact is mandatory.

The invoice.paymentMeansArray must include at least a single payment means.

Storecove automatically includes the DE:LWID in the BuyerReference when sending to a DE:LWID and you have not provided an DE:LWID in the BuyerReference yourself.

7.1.6. ES - Spain

For B2B, provide an ES:DIRE routing identifier and an ES:VAT tax identifier. The invoice will then be routed through the FACeB2B network. There are a few additional requirements:

both sender and receiver must be an ES company;
you must have a "credit_transfer" PaymentMean;
the "dueDate" property is mandatory.

For B2G, provide three ES:FACE identifiers in the routing object, as well as the ES:VAT tax identifier in the accountingCustomerParty.publicIdentifiers. The invoice will then be routed through the FACe network. The three required ES:FACE identifiers are as follows:

  "routing": {
    "eIdentifiers":[
      {
        "scheme": "ES:FACE",
        "id": "L01234567",
        "role": "es_01_fiscal"
      },
      {
        "scheme": "ES:FACE",
        "id": "L01234567",
        "role": "es_02_receptor"
      },
      {
        "scheme": "ES:FACE",
        "id": "L01234567",
        "role": "es_03_pagador"
      }
    ]
  }

The roles are:

ES-01-FISCAL: Oficina Contable.
ES-02-RECEPTOR: Órgano Gestor. This is the routing identifier for the accountingCustomerParty.
ES-03-PAGADOR - Unidad Tramitadora.

To find these identifiers, use this link and download the "Listado de información básica de unidades orgánicas de las CCAA".

There are a few additional requirements:

you must have a "credit_transfer" PaymentMean;
the "dueDate" property is mandatory.

7.1.7. FI - Finland

For Finvoice, provide an FI:OPID routing identifier and an FI:OVT legal identifier. An FI:VAT is recommended. In many cases (depending on the sender/receiver country and the type of service/goods) an FI:VAT is required. So we recommend always including this.

7.1.8. FR - France

The POC for the upcoming French eReporting/eInvoicing requirements has been put on hold. We will update when there is news. Whatever solution is implemented by France will be support by Storecove as a PDP.

When sending invoices to the French government (Chorus Pro):

All invoices have to be routed to SIRET 0009:11000201100044. There is no test environment for sending to public entities.
The SIRET / 0009 identifier of the final recipient is to be included in the invoice.accountingCustomerParty.publicIdentifiers array.
The service code must be sent in invoice.buyerReference (deprecated) or the invoice.references array (documentType buyer_reference)
The commitment number must be sent in the invoice.orderReference (deprecated) or the invoice.references array (documentType purchase_order).

Invoices to companies (SIRET / 0009 or SIRENE / 0002) are routed directly to that identifier.

7.1.9. IT - Italy

There are several scenarios.

IT Sender, IT Receiver, B2B/B2G
Provide the receiver IT:VAT and the receiver IT:CUUO (codice destinatario)
IT Sender, IT Receiver, B2C
Provide the receiver IT:CF and the receiver IT:CUUO (codice destinatario)
IT Sender, non-IT Receiver
Provide the receiver tax identifier and any routing identifier applicable to the receiving country (see Receiver Identifiers).
non-IT Sender, IT Receiver, B2B/B2G
Provide the receiver IT:VAT and the receiver IT:CUUO (codice destinatario)
non-IT Sender, IT Receiver, B2C
Provide the receiver IT:CF and an optional email. The invoice will be eReported and sent via email. Note that this cannot be a PEC email address.

7.1.10. MY - Malaysia

Malaysia is working on implementing two things:

Commercial invoice delivery

The Malaysian government has jonied the Peppol network! LHDNM approved invoices can be digitally sent to receivers. The Peppol Authority is MDEC (Malaysia Digital Economy Corporation).

Identifiers

Storecove has made the Malaysian identifier schemes
- MY:EIF (BRN, b2b & b2g)
- MY:TIN (TIN, b2b & b2g)
- MY:SST (SST, b2b & b2g)
- MY:TTX (Tourism Tax, b2c)
- MY:ARMY (Army id, b2c)
- MY:PASSPORT (Malaysian passport id, b2c)
- MY:NRIC (National Registration Identity Card, b2c)
available for use with LHDNM and in the Peppol network. The roles for these identifiers is that the MY:EIF is used for routing on the Peppol network and a the same time is the BRN. The sender’s MY:TIN is mandatory to be included. Therefore, a valid LegalEntity will always have at least two identifiers. The MY:SST is only used for companies that have an SST. In that case, it is mandatory.

The structure of the MY:TIN is "X(X)00000000000", where "X(X)" is from the list EI|IG|SG|OG|C|CS|D|E|F|FA|PT|TA|TC|TN|TR|TP|J|LE and is followed by 9, 10 or 11 numbers.

The structure of the MY:SST is 15 alphanumeric characters.

The structure of the MY:EIF is "nnAAAAAAAAAAAA", where "nn" is a type identifier from the following list:

01: SSM number (12 digit)
02: Sabah (5 digit)
03: Sarawak (5 digit)
04: Foreign business entity (max 12 characters, starting with the ISO3166-1 alpha-2 country code)
05: Not supported. Use the sandbox.
06: Associations and Cooperations

Starting from October 2019, the SSM (Suruhanjaya Syarikat Malaysia) has changed to a 12-digit format. The first four digits are the year of incorporation; the next two digits represent the type of business entity registered or incorporated; and the final six digits are unique from a running sequence.

Test identifier

Storecove has registered the Malaysian test identifier "01202401123456" (see Test Identifiers) on the Peppol network, so you can send test invoices to this identifier.
PINT (Peppol INTernational) has been fully implemented by Storecove. This means that
- For sending, you provide us with the JSON and we will generate the correct PINT document. We will then handle the following scenarios:
  - For domestic, we will generate a PINT-MY.
  - For cross-border, we will either
    
    generate a PINT-MY (if the receiver supports PINT-*) OR
    
    generate a document in the receiver country’s format.
- If your LegalEntity is also a receiver, we will advertise both PINT-MY and the global PINT-*, so you can expect to receive not only domestic, but also cross-border PINT documents. In the latter case, we will localize the received document into a JSON that you can process in your system, without having to worry about foreign taxes.

CTC - hard clearance

The LHDNM (Lembaga Hasil Dalam Negeri Malaysia, the Inland Revenue Board Of Malaysia) has introduced a system whereby invoices that are sent must first be approved by the LHDNM. Important features are:

Routing

Because using this network is not yet mandatory for all Malaysian companies, the default workflow is to not use this network. Therefore, you have to force its use:
```
"routing": {
  "eIdentifiers": [
    {
        "scheme": "MY:EIF",
        "id": "01202401123456"
    }
  ],
  "networks": [
    {
      "application": "my-lhdnm",
      "settings": {
        "enabled": true
      }
    }
  ]
}
```
If you enable use of this network, the following workflow will be followed: first, your invoice will be sent to the LHDNM system and after approval the invoice will be sent via Peppol/DBNAlliance or email if the recipient is not on one of these Exchange networks (if you provided an email address).
LHDNM Authorization

Storecove can send invoices on behalf of any Malaysia company! The only thing required is that you authorize us to send on your behalf. The guide can be found here. Note for whitelabel customers: you should create a similar document for your customers.
LHDNM Specific Document Types

The LHDNM system requires the document types defined here. To use these, the following rules apply:
- The distinction between invoice and creditnote is automatically made based on the sign of the total document amount. There is a field "preferredInvoiceType" that influences this for edge cases where an invoice is sent, but due to corrections on previous invoices it has a negative total but should be treated as an invoice. This field is ignored when sending to the LHDNM, however it can influence a subsequent delivery to the receiver via Peppol.
- To trigger a debit note, issue an invoice (i.e. a positive total amount) and include a reference with type "billing" that references the original invoice that this debit note has additional charges for. We will then automatically use type debit note instead of invoice. Note that this billing reference must include both the "documentId" and the "documentUuid".
- To trigger a refund_note, issue a credit note (i.e. a negative total amount) and include "preferredInvoiceType": "prefer_refundnote".
- Examples of each document type can be found below.
- Self billing is controlled by the "selfBillingMode" flag. For details see Invoice. When using this flag to report an invoice that was received to a tax authority, use the following flow chart:
  
  Storecove does not provide OCR services and does not have a page for entering invoices manually. As an alternative, invoices can be entered directly into the MyInvois system.
  
  The "invoice_report" document is currently being implemented. It JSON is very simple, just like an invoice response:
  { "receiveGuid": "b09c5397-65cc-40b6-8274-264f487c1649", "document": { "documentType": "invoice_report", "invoiceReport": { "action": "send" } } }
  The "receiveGuid" is the "document_guid" inside the "received_document" webhook.
LHDNM Tax codes

See Tax for MY specific tax codes. These will be automatically mapped to the LHDNM tax codes.
State codes

We use the ISO 3166-2:MY codes for the states in Malaysia. These are prefixed with the country code, e.g. 'MY-01', etc.
MSIC

The MSIC code of a legal entity can be added through the API (field: LegalEntity.classificationCode) or the UI (currently being added). It will be automatically included in each invoice.
PDF Stamping

The section PDF Stamping explains how to setup a PDF for stamping with the QR code with the deep link to the invoice in the MyInvois portal. Note that the "{{IRN}}" field is not used for Malaysia.

Clearing evidence

The clearing evidence for LHDNM looks like this:

{
  "sender": "0230:01202411111111",
  "receiver": "LHDNM",
  "documents": [
    {
      "mime_type": "application/xml",
      "document": "url to GET the document from",
      "expires_at": "1970-01-01 00:00:00Z"
    }
  ],
  "evidence": {
    {
      "transmission_id": "the id of the transmission batch assigned by LDNM",
      "partner_key": "the UUID assigned by LDNM",
      "long_id": "the Long ID assigned by LDNM",
      "validated_at": "1970-01-01 00:00:00Z"
    }
  }

The documents array will have a single XML document, which is the signed document we sent to LHDNM.

LHDNM Specific Fields

In most cases, you won’t need any of the LHDNM specific fields. However, there is one field that is non-standard and is required for all invoice lines: the category of product or services being billed called "classification code". This can be added as follows:

{
  "document": {
    "invoice": {
      "invoiceLines": [
        {
          "references": [
            {
              "documentType": "item_classification_code",
              "documentIdListId": "CLASS",
              "documentId": "003"
            }
          ]
        }
      ]
    }
  }
}

The other cases are:

for transactions where goods are shipped to a different recipient and/or address (i.e., different from the Buyer’s details in the accountingCustomerParty):

{
  "document": {
    "invoice": {
      "delivery": {
        "deliveryParty": {
          "party": {
            "companyName": "Delivery Taking Company",
            "address": {
              "street1": "Streety 123",
              "street2": null,
              "city": "Kuala Lumpur",
              "zip": "0000000",
              "county": "MY-14",
              "country": "MY"
            }
          },
          "publicIdentifiers": [
            {
              "scheme": "MY:TIN",
              "id": "LE00000000000"
            },
            {
              "scheme": "MY:EIF",
              "id": "01202401123456"
            }
          ]
        }
      }
    }
  }
}

when importing or exporting goods

mandatory import/export fields:

{
  "document": {
    "invoice": {
      "deliveryTerms": {
        "incoterms": "EXW"
      },
      "references": [
        {
          "documentType": "my_customs_form_1_9",
          "documentId": "Reference Number of Customs Form No.1, 9, etc."
        }
      ]
    }
  }
}

optional import/export fields:

{
  "document": {
    "invoice": {
      "invoiceLines": [
        {
          "references": [
            {
              "documentType": "item_classification_code",
              "documentIdListId": "PTC",
              "documentId": "123456"
            }
          ]
        }
      ],
      "references": [
        {
          "documentType": "my_customs_form_2",
          "documentId": "Reference Number of Customs Form No.2"
        },
        {
          "documentType": "free_trade_agreement",
          "documentId": "Free Trade Agreement"
        }
      ],
      "delivery": {
        "shipment": {
          "originAddress": {
            "country": "SG"
          },
          "allowanceCharges": [
            {
              "amountExcludingTax": 1234,
              "reason": "why?",
              "taxesDutiesFees": [
                {
                  "category": "exempt",
                  "country": "MY",
                  "percentage": 0.0
                }
              ]
            }
          ]
        }
      }
    }
  }
}

The following gives the JSON object for an MY invoice with all MY features:

Full MY features Invoice

The following are JSON examples for different document types:

Consolidated (B2C)
Credit Note
Debit Note
Refund Note

7.1.11. NL - The Netherlands

When sending to public entities, the invoice.accountingSupplierParty.party.contact.email is mandatory.

Dutch senders and receivers require a legal identifier. For companies, this is NL:KVK, for public entities this is NL:OINO.

7.1.12. NZ - New Zealand

New Zealand uses a GLN to identify businesses. In addition, when sending invoices to a New Zealand customer, make sure you include the pseudo identifier NZ:GST as their tax identifier.

7.1.13. PL - Poland

Poland has a V-model type network. This means that all invoices are routed to a central hub, which then routes the invoice to the correct Polish recipient. If the recipient is not Polish, Storecove will automatically schedule a seconday delivery action which is either an Exchange network (Peppol, DBNAlliance) or email.

Because using this network is not yet mandatory, the default workflow is to not use this network. Therefore, you have to force its use, as follows:

"routing": {
  "eIdentifiers": [
    {
        "scheme": "PL:VAT",
        "id": "PL0101010101"
    }
  ],
  "networks": [
    {
      "application": "pl-ksef",
      "settings": {
        "enabled": true
      }
    }
  ]
}

Note this will only work if your LegalEntity has been setup for this network. Contact us on helpdesk@storecove.com if you want this.

7.1.14. RO - Romania

Romania has a V-model type network. This means that all invoices are routed to a central hub, which then routes the invoice to the correct Romanian recipient. If the recipient is not Romanian, Storecove will automatically schedule a seconday delivery action which is either an Exchange network (Peppol, DBNAlliance) or email.

Because using this network is not yet mandatory, the default workflow is to not use this network. Therefore, you have to force its use, as follows:

"routing": {
  "eIdentifiers": [
    {
        "scheme": "RO:VAT",
        "id": "RO010101010"
    }
  ],
  "networks": [
    {
      "application": "ro-anaf",
      "settings": {
        "enabled": true
      }
    }
  ]
}

Note this will only work if your LegalEntity has been setup for this network. Contact us on helpdesk@storecove.com if you want this.

The county field for a Romania address must use the ISO3166-2:RO codes, e.g. "RO-AB, RO-AR". Don’t omit the country prefix!

The city field for county RO-B must be SECTOR1 - SECTOR6.

7.1.15. SG - Singapore

Singapore has some specific requirements:

The SG:UEN identifier must be advertised in the Singapore SMP. This ability has to be setup by Storecove in advance for your organization. To add an SG:UEN identifier, the owner of the SG:UEN must go through a CorpPass approval process.
The Singapore tax authority, IRAS, is implementing a system whereby every invoice sent and received must be reported to the tax authority. To allow Storcove to do this for a legal entity, the owner of the legal entity must authorize Storecove to send on their behalf through a CorpPass approval process.
for B2G, the Singapore government has a specific set of rules for sending invoices to them.

Each will be discussed below.to

Creating an SG:UEN in the Singapore SMP

There are two ways to create an SG:UEN identifier:

Through the Storecove UI; * this is still being implemented, expected 4Q24 *
Through the Storecove API.

The Storecove UI supports the email process only, meaning your customer will be sent an email by the SMP containing a link to the CorpPass system. After logging in, the approval is given to advertise the SG:UEN on the Peppol network. It is available for Enterprises and Resellers, not for Cloud Accounting customers. This process has the following steps:

Create the LegalEntity, including the SG:UEN
Wait for the LegalEntity to be approved
Initiate the authorization process by clicking the approprate button in the Storecove UI.

The Storecove API supports both the email and the redirect process, but it is only available for Cloud Accounting customers. This process has the following steps:

Create the LegalEntity through the API
Create the SG:UEN through the API, making sure you include the CorpPassCreate object. Use the following endpoint:

PeppolIdentifiers

The CorpPass object is mandatory for SG:UEN identifiers. There are two flavours:

The email flow

This flow works as follows:
- You provide a name and an email address when creating the participant identifier;
- An email is sent to this email address, with a (unique) link to the CorpPass system where the user can confirm their identity;
- When the user completes the identification process, the identifier is created on the Peppol network;
- Some time later (this may be up to 24 hours) the identifier will become active on the Storecove system;
The redirect flow

This flow is more complicated to implement, but yields a better user experience. It looks like redirecting to an external payment system in a webshop. Once the payment is done, you go back to the success page (if the payment was successful)

This flow works as follows. You provide two URLs when creating the identifier:
- one back to your site that will be called when identification was successful;
- one back to your site that will be called when identification has failed.
When you create the identifier you will receive the CorpPass URL to redirect to, like this:

+
```
window.location.href = "CorpPass URL here";
```
When the process ends, one of your URLs is called. Upon success, the identifier is immediately available on the Peppol network. Upon failure, the identifier will be automatically deleted. Then, to restart the process, simply re-create the identifier. If the process does not end, because your user does not finish it, you can also simply re-create the identifier. We will recognize that the identifier already exists, but is in a CorpPass process, and provide you with a fresh CorpPass redirect URL.

+ To support the process of developing the redirect flow, Storecove provides the "simulate_corppass" property in the CorpPass object. Setting this to true (which is only possible in sandbox) will simulate the CorpPass process, sending you to a Storecove page with two buttons: one for success and one for failure. Clicking one of these will call the appropriate URL you provided when creating the identifier.

IRAS Reporting

The IRAS reporting is done by Storecove on behalf of the legal entity. The legal entity must authorize Storecove to do this. The authorization process is done through CorpPass, just like the SMP authorization process. There are two ways to authorize Storecove to send on behalf of an SG:UEN identifier:

through the Storecove UI; * this is still being implemented, expected 4Q24 *
through the Storecove API. * this is still being implemented, expected 4Q24 *

Both ways require that you have first gone through the process of creating an SG:UEN in the Singapore SMP. You cannot comply with the IRAS requirements without receiving invoices via Peppol.

The Storecove UI supports the email process only, meaning your customer will be sent an email by the IRAS system containing a link to the CorpPass system. After logging in, the approval is given to Storecove to report invoices on behalf of the LegalEntity. It is available for Enterprises and Resellers, not for Cloud Accounting customers. This process has the following steps:

initiate the authorization process by clicking the approprate button in the Storecove UI. * update: the UI for this will be ready 4Q24 *

The Storecove API supports both the email and the redirect process, but it is only available for Cloud Accounting customers. This process has the following steps:

initiate the process by calling the appropriate endpoint in the Storecove API. * update: the API for this will be ready 4Q24 *

The reporting process for sales invoices works as follows:

Send your invoice via Peppol, as normal
After sending via Peppol, Storecove will report the invoice to the IRAS system if you include this in the routing object:

{
  "routing": {
    "eIdentifiers": [
      {
        "scheme": "SG:UEN",
        "id": "SGUEN2401123456"
      }
    ],
    "networks": [
      {
        "application": "sg-iras",
        "settings": {
          "enabled": true,
          "mock": true
        }
      }
    ]
  }
}

In this example, the mock keyword is used in the settings object to enable the simulation of requests to IRAS. This currently required as we complete work on the actual IRAS connection.

For received invoices, use the "invoice_report" document that is currently being implemented. It JSON is very simple, just like an invoice response:

{
  "receiveGuid": "b09c5397-65cc-40b6-8274-264f487c1649",
  "document": {
    "documentType": "invoice_report",
    "invoiceReport": {
      "action": "send"
    }
  }
}

The "receiveGuid" is the "document_guid" inside the "received_document" webhook. * this functionality is expected by January 2025. *

This reporting process only works for invoices received via Peppol.

Sending to Singapore Government Organizations (not reporting)

For sending to the Singapore government there are a number of specific rules to follow:

Make sure you have a CorpPass account at CorpPass portal (corppass.gov.sg)
Make sure you have have an approved vendor record at Vendors@Gov (vendors.gov.sg).
Either 3a. Route to endpoint of the Accountant-General’s Department: 0195:SGUENT08GA0028A; OR 3b. Route directly to the government organization’s SG:UEN. All these were individually registered by the Singapore government 3Q2024!
The accountingCustomerParty.party.contact.email is mandatory.
The accountingSupplierParty.party.contact.email is mandatory.
The property invoice.references array (with documentType buyer_reference) must contain the Business Unit. This is one of this list:
- List of Ministries / Statutory Boards
invoice.prepaidAmount is not acceptable.
invoice.payableRoundingAmount are not acceptable. Evertyhing must round perfectly!
the invoice.references array (with documentType purchase_order) may be mandatory. To find out whether you need to bill against an Invoicing Instruction/Purchase Order, enquire with your client agency.
When invoicing against an Invoicing Instruction/Purchase Order, invoice.invoiceLines.orderLineReferenceLineId must hold the corresponding LineID of the Order.
Only a single attachment is allowed and only PDF.

When sending to Singapore companies, no specific rules apply and you can use the individual company’s UEN for routing.

7.1.16. SE - Sweden

Although not a formal network, in Sweden we have the capatility to deliver invoices to the "Svefaktura" co-operation of local Swedish service providers. Routing is through the SE:ORGNR together with a network specification:

"routing": {
  "eIdentifiers": [
    {
        "scheme": "SE:ORGNR",
        "id": "0012345674"
    }
  ],
  "networks": [
    {
      "application": "svefaktura",
      "settings": {
        "enabled": true
      }
    }
  ]
}

Use of the "Svefaktura" co-operation can also be induced by specifying an operator id, as follows:

"routing": {
  "eIdentifiers": [
    {
        "scheme": "SE:ORGNR",
        "id": "0012345674"
    },
    {
        "scheme": "SE:OPID",
        "id": "1234567890"
    }
  ]
}

Before using these Sweden-specific routing options, you must be sure your receiver is actually reachable through the "Svefaktura" co-operation.

7.2. Sender Identifiers

Region

Country

Legal

Tax

Americas

DUNS, GLN, LEI

US:EIN, US:SSN

Americas

CA:CBN

Americas

MX:RFC

AUNZ

AU:ABN

AUNZ

GLN

NZ:GST

GLN

EEA

CH:UIDB

CH:VAT

EEA

IS:KTNR

IS:VAT

EEA

LI:VAT

EEA

NO:ORG

NO:VAT

AD:VAT

AL:VAT

AT:VAT

BA:VAT

BE:EN

BE:VAT

BG:VAT

CY:VAT

CZ:VAT

DE:LWID

DE:VAT. DE:STNR can be used if you don’t have a VAT number.

DK:DIGST

DK:ERST

EE:CC

EE:VAT

ES:VAT

FI:OVT

FI:VAT

FR:SIRENE or FR:SIRET

FR:VAT

GR:VAT

HR:VAT

HU:VAT

IE:VAT

IT:IVA

IT:CF and/or IT:IVA

IT:CF

IT:IVA

LT:LEC

LT:VAT

LU:MAT (Matricule; optional), LU:RCS (Registre de Commerce; optional)

LU:VAT

LV:VAT

MC:VAT

ME:VAT

MK:VAT

MT:VAT

NL:KVK

NL:VAT

PL:VAT

PT:VAT

RO:VAT

RS:VAT

SE:ORGNR

SE:VAT

SI:VAT

SK:VAT

SM:VAT

TR:VAT

VA:VAT

IN:GSTIN

JP:SST (deprecated: JP:LIN)

JP:IIN (deprecated: JP:TIN)

MY:EIF

MY:TIN

SG:UEN

SG:GST (optional)

World

GB:VAT

World

SA:TIN

World

Other

DUNS, GLN, LEI

7.3. Receiver Identifiers

Region

Country

B2X

Legal

Tax

Routing

Americas

DUNS, GLN, LEI

US:EIN, US:SSN

DUNS, GLN, LEI

Americas

CA:CBN

Americas

MX:RFC

AUNZ

B+G

AU:ABN

AUNZ

B+G

GLN

NZ:GST

GLN

EEA

B+G

CH:UIDB

CH:VAT

CH:UIDB

EEA

B+G

IS:KTNR

IS:VAT

IS:KTNR

EEA

B+G

LI:VAT

EEA

B+G

NO:ORG

NO:VAT

NO:ORG

B+G

AD:VAT

B+G

AL:VAT

AT:GOV

Centralized id: 9915:b

AT:VAT

B+G

BA:VAT

B+G

BE:EN

BE:VAT

BE:EN

B+G

BG:VAT

B+G

CY:VAT

B+G

CZ:VAT

DE:LWID

DE:VAT

B+G

DK:DIGST

DK:ERST

DK:DIGST

B+G

EE:CC

EE:VAT

EE:CC

ES:VAT

B+G

FI:OVT

FI:VAT

FI:OVT

FR:SIRET + customerAssignedAccountIdValue

Centralized id: 0009:11000201100044

FR:SIRENE or FR:SIRET

FR:VAT

FR:SIRENE or FR:SIRET

B+G

GR:VAT

B+G

HR:VAT

B+G

HU:VAT

B+G

IE:VAT

G (Peppol)

IT:IVA

IT:CUUO

B (SDI)

IT:CF and/or IT:IVA

IT:CUUO

C (SDI)

IT:CF

G (SDI)

IT:IVA

IT:CUUO

B+G

LT:LEC

LT:VAT

LT:LEC

B+G

LU:VAT

B+G

LV:VAT

B+G

MC:VAT

B+G

ME:VAT

B+G

MK:VAT

B+G

MT:VAT

NL:OINO

NL:KVK

NL:VAT

NL:KVK or NL:VAT

G+B

PL:VAT

G+B

PT:VAT

G+B

RO:VAT

G+B

RS:VAT

G+B

SE:ORGNR

SE:VAT

SE:ORGNR

G+B

SI:VAT

G+B

SK:VAT

G+B

SM:VAT

G+B

TR:VAT

G+B

VA:VAT

IN:GSTIN

JP:SST (deprecated: JP:LIN)

JP:IIN (deprecated: JP:TIN)

JP:SST

MY:EIF

MY:TIN

MY:EIF

SG:UEN with special requirements

Centralized id: 0195:SGUENT08GA0028A

SG:UEN

SG:GST (optional)

SG:UEN

World

GB:VAT

World

SA:TIN

World

Other

DUNS, GLN, LEI

7.4. Test Identifiers

Peppol

Storecove offers the following test identifiers to send test invoices to via the various test networks:

Country

Peppol

DBNAlliance

SDI

Finvoice

AD:VAT AD20394939

AT:VAT ATU87654321

AT:GOV test (and include customerAssignedAccountIdValue)

AU:ABN 20234567890 (regular), AU:ABN 92873837267 (with self billing)

BE:EN 0112233453

BG:VAT BG010101010

CH:UIDB CHE123456785

CY:VAT CY33043933X

CZ:VAT CZ01010101

DE:LWID 10101010-STO-10

DE:VAT DE010101010

DK:DIGST DK10101011

EE:CC 10919191

EE:VAT EE010101010

ES:VAT ESB53625999

FI:VAT FI01010101 (deprecated); FI:OVT 003708888888CCC

Routing FI:OPID 003721291126 with business identifier FI:OVT 003708888888CCC

FR:SIRENE 123456987

GB:VAT GB303939483

GR:VAT EL999999999

HR:VAT HR01010101010

HU:VAT HU01010101

IE:VAT IE4947949ED

IS:KTNR 4343454311

IT:CUUO SCSCSCS

No SDI Test Network. Use IT:CUUO SCSCSCS (will not get sent)

JP:SST 9234567899123 (regular), JP:SST 8234567890124 (with self billing)

LI:VAT 1293495

LT:LEC 29202928282

LT:VAT LT010101010

LU:VAT LU01010101

LV:VAT LV01010101010

MY:EIF 01202401123456 (regular), MY:EIF 01202401123457 (with self billing)

NL B2B

NL:KVK 012345677, NL:VAT NL000000000B45

NL B2G

NL:OINO 10101010101010101010

NO:ORG 010101018

GLN 1200109837203

PL:VAT PL0101010101

PT:VAT PT123456789

RO:VAT RO010101010

SE:ORGNR 0012345674

SG:UEN SGTST123457890SC

SI:VAT SI01010101

SK:VAT SK0101010101

GLN 1200109963131

Storecove API Documentation

1. Introducing Storecove

1.1. Getting Started

1.1.1. Register for API access

1.1.2. Create an API key

1.1.3. Make your first API call

1.1.4. Create a sender

1.1.5. Send your first invoice

1.1.6. Sent! (Retrieve the Sending Evidence)

What if my Customer is not on one of the Exchange networks (Peppol, DBNAlliance)?

2. Using the API

2.1. API keys

2.2. Webhooks

2.3. API tools

2.3.1. Client Libraries

2.3.2. Postman

2.3.3. Swagger Codegen

2.4. camelCase or snake_case?

3. Building Your Solution

3.1. Environments

3.2. Legal Entities

3.2.1. Actors

3.2.2. Identifiers

Types

Structure

Which identifiers for my LegalEntity?

3.2.3. Additional Tax Identifiers

3.3. Sending Documents

3.3.1. Sending Workflow

Invoice Sending Workflow

1. CTC Compliance

2. Tax Compliance

3. Exchange networks

4. Static routes

5. Email

3.3.2. Sending a document

Invoice

Tax System

General Data

Modifiers

Parties

References

Delivery Details

Payment

Invoice Lines

Allowances and Charges

Summary Amounts

3.3.3. JSON Object

Invoice

Invoice Response

Order

3.3.4. Webhooks for Sending

Invoice Submission

Document Submission

3.3.5. Sending Evidence

3.3.6. Globalization

3.3.7. Advanced Routing

3.3.8. PDF Stamping

3.4. Receiving Documents

3.4.1. Receiving Flows

3.4.2. Received Document Webhook

3.4.3. Document Formats

3.4.4. JSON Object Invoice

Change Log

3.4.5. JSON Object Order

4. Various Deprecated

4.1. Reporting

Sending Sales Invoices

Receiving Purchase Invoices

Sending Sales Invoices

Receiving Purchase Invoices

4.2. Email Ingestion

4.2.1. Introduction

4.2.2. From: Address

4.2.3. To: Address

4.2.4. Attachments

Data

PDF

4.3. SFTP Ingestion

4.3.1. Introduction