Looking for deprecated properties or endpoints? Visit https://www.storecove.com/docs/with_deprecated

1. Introducing Storecove

Storecove is the only international operating Peppol accesspoint that offers a one-stop e-invoicing solution. 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 sandbox API environment, register here

The last step is very important for the type of account that is created, so choose carefully. This will impact the remainder of this 5-minute how-to!

1.1.2. Create your API key

Create a new API key by clicking the "Create New API Key" button. For the Integrator package, create a "Master" key.

1.1.3. Make your first API call

Create a file "discovery.json" with the following contents:

{
  "documentTypes": ["invoice"],
  "network": "peppol",
  "metaScheme": "iso6523-actorid-upis",
  "scheme": "nl:kvk",
  "identifier":"60881119"
}

or, for the BPC network, use

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

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 the (TEST) Peppol as well as BPC network, the response is

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

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 and IT additional setup steps are required and so to test this you need to contact us first.

How the LegalEntity is created, depends on the type of account you have. Click the correct tab below to see how to create a LegalEntity:

For a company account, creating a LegalEntity is done in the UI, on

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 for this type of account.

In the integrator account you have two choices:

  1. create the LegalEntity in the UI. To create the LegalEntity in the UI, go to

    • https://app.storecove.com/senders 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.

  2. create the LegalEntity through the API

Creating the LegalEntity through the API involves two steps:

  1. Creation of the actual LegalEntity

  2. Creation of the participant identifiers that identify the LegalEntity for legal and tax purposes.

For the first step, create a file called "legal_entity.json" with the following contents:

{
	"party_name": "Test Party",
	"line1": "Test Street 1",
	"city": "Test City",
	"zip": "Zippy",
	"country": "DE"
}
Carefully choose the country.

Next, call the API:

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" \
--data @legal_entity.json

The response will ook like this:

{
    "id":  123456789,
    "party_name": "Test Party",
    "line1": "Test Street 1",
    "city": "Test City",
    "zip": "Zippy",
    "country": "SE",
    "public": true,
    "advertisements": ["invoice"],
    "api_keys": [ "LEGAL_ENTITY_API_KEY" ]
}

Note down the "id" and "api_keys" properties: we will need these!

Now, lets add a legal identifier, tax identifier or both, depending on what you find in this list:

Region Country Legal Tax

Americas

US

DUNS, GLN, LEI

US:EIN, US:SSN

Americas

CA

CA:CBN

Americas

MX

MX:RFC

AUNZ

AU

AU:ABN

AUNZ

NZ

GLN

NZ:GST

CN

CN

GLN

EEA

CH

CH:UIDB

CH:VAT

EEA

IS

IS:KTNR

IS:VAT

EEA

LI

LI:VAT

EEA

NO

NO:ORG

NO:VAT

EU

AD

AD:VAT

EU

AL

AL:VAT

EU

AT

AT:VAT

EU

BA

BA:VAT

EU

BE

BE:EN

BE:VAT

EU

BG

BG:VAT

EU

CY

CY:VAT

EU

CZ

CZ:VAT

EU

DE

DE:LWID

EU

DE

DE:VAT

EU

DK

DK:DIGST

DK:ERST

EU

EE

EE:CC

EE:VAT

EU

ES

ES:VAT

EU

FI

FI:ORG

FI:VAT

EU

FR

FR:SIRENE or FR:SIRET

FR:VAT

EU

GR

GR:VAT

EU

HR

HR:VAT

EU

HU

HU:VAT

EU

IE

IE:VAT

EU

IT

IT:IVA

EU

IT

IT:CF and/or IT:IVA

EU

IT

IT:CF

EU

IT

IT:IVA

EU

LT

LT:LEC

LT:VAT

EU

LU

LU:MAT (Matricule PM; optional)

LU:VAT

EU

LV

LV:VAT

EU

MC

MC:VAT

EU

ME

ME:VAT

EU

MK

MK:VAT

EU

MT

MT:VAT

EU

NL

NL:KVK

NL:VAT

EU

PL

PL:VAT

EU

PT

PT:VAT

EU

RO

RO:VAT

EU

RS

RS:VAT

EU

SE

SE:ORGNR

SE:VAT

EU

SI

SI:VAT

EU

SK

SK:VAT

EU

SM

SM:VAT

EU

TR

TR:VAT

EU

VA

VA:VAT

IN

IN

IN:GSTIN

JP

JP

JP:SST (alias: JP:LIN, use is discouraged)

JP:IIN (deprecated: JP:TIN)

SG

SG

SG:UEN

SG:GST (optional)

World

GB

GB:VAT

World

SA

SA:TIN

World

Other

DUNS, GLN, LEI

You should create both identifiers if the list specifies that. Otherwise, your LegalEntity will be incomplete and not able to send invoices.

To create an identifier, first create a file "identifier.json" like this:

{
	"superscheme": "iso6523-actorid-upis",
	"scheme": "DE:VAT",
	"identifier": "DE123456789SC"
}

And create it with

curl \
-X POST "https://api.storecove.com/api/v2/legal_entities/LEGAL_ENTITY_ID_HERE/peppol_identifiers" \
-H "Accept: application/json" \
-H "Authorization: Bearer API_KEY_HERE" \
-H "Content-Type: application/json" \
--data @identifier.json
Swap the "LEGAL_ENTITY_ID_HERE" and the "API_KEY_HERE" for the id and API key you received when creating it.

Creating the LegalEntity through the API involves two steps:

  1. Creation of the actual LegalEntity

  2. Creation of the participant identifiers that identify the LegalEntity for legal and tax purposes.

For the first step, create a file called "legal_entity.json" with the following contents:

{
	"party_name": "Test Party",
	"line1": "Test Street 1",
	"city": "Test City",
	"zip": "Zippy",
	"country": "DE"
}
Carefully choose the country.

Next, call the API:

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" \
--data @legal_entity.json

The response will ook like this:

{
    "id":  123456789,
    "party_name": "Test Party",
    "line1": "Test Street 1",
    "city": "Test City",
    "zip": "Zippy",
    "country": "DE",
    "public": true,
    "advertisements": ["invoice"]
}

Note down the "id" property: we will need this!

Now, lets add a legal identifier, tax identifier or both, depending on what you find in this list:

Region Country Legal Tax

Americas

US

DUNS, GLN, LEI

US:EIN, US:SSN

Americas

CA

CA:CBN

Americas

MX

MX:RFC

AUNZ

AU

AU:ABN

AUNZ

NZ

GLN

NZ:GST

CN

CN

GLN

EEA

CH

CH:UIDB

CH:VAT

EEA

IS

IS:KTNR

IS:VAT

EEA

LI

LI:VAT

EEA

NO

NO:ORG

NO:VAT

EU

AD

AD:VAT

EU

AL

AL:VAT

EU

AT

AT:VAT

EU

BA

BA:VAT

EU

BE

BE:EN

BE:VAT

EU

BG

BG:VAT

EU

CY

CY:VAT

EU

CZ

CZ:VAT

EU

DE

DE:LWID

EU

DE

DE:VAT

EU

DK

DK:DIGST

DK:ERST

EU

EE

EE:CC

EE:VAT

EU

ES

ES:VAT

EU

FI

FI:ORG

FI:VAT

EU

FR

FR:SIRENE or FR:SIRET

FR:VAT

EU

GR

GR:VAT

EU

HR

HR:VAT

EU

HU

HU:VAT

EU

IE

IE:VAT

EU

IT

IT:IVA

EU

IT

IT:CF and/or IT:IVA

EU

IT

IT:CF

EU

IT

IT:IVA

EU

LT

LT:LEC

LT:VAT

EU

LU

LU:MAT (Matricule PM; optional)

LU:VAT

EU

LV

LV:VAT

EU

MC

MC:VAT

EU

ME

ME:VAT

EU

MK

MK:VAT

EU

MT

MT:VAT

EU

NL

NL:KVK

NL:VAT

EU

PL

PL:VAT

EU

PT

PT:VAT

EU

RO

RO:VAT

EU

RS

RS:VAT

EU

SE

SE:ORGNR

SE:VAT

EU

SI

SI:VAT

EU

SK

SK:VAT

EU

SM

SM:VAT

EU

TR

TR:VAT

EU

VA

VA:VAT

IN

IN

IN:GSTIN

JP

JP

JP:SST (alias: JP:LIN, use is discouraged)

JP:IIN (deprecated: JP:TIN)

SG

SG

SG:UEN

SG:GST (optional)

World

GB

GB:VAT

World

SA

SA:TIN

World

Other

DUNS, GLN, LEI

You should create both identifiers if the list specifies that. Otherwise, your LegalEntity will be incomplete and not able to send invoices.

To create an identifier, first create a file "identifier.json" like this:

{
	"superscheme": "iso6523-actorid-upis",
	"scheme": "DE:VAT",
	"identifier": "DE123456789SC"
}

And create it with

curl \
-X POST "https://api.storecove.com/api/v2/legal_entities/LEGAL_ENTITY_ID_HERE/peppol_identifiers" \
-H "Accept: application/json" \
-H "Authorization: Bearer API_KEY_HERE" \
-H "Content-Type: application/json" \
--data @identifier.json
Swap the "LEGAL_ENTITY_ID_HERE" for the id you received when creating 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

SG

AU/NZ

FI

IN

JP

SA

US

World

EU/EEA

Any EU => DE (B2G)

Any EU => NL (B2B)

Any EU => NL (B2G)

ES => ES (FACeB2B)

Any EU=> SG

Any EU => SG (export)

 

 

 

 

 

 

Contact Us

SG

 

SG => SG

 

 

 

 

 

 

Contact Us

AU/NZ

AU => DE

 

AU => AU

AU => NZ

NZ => NZ

NZ => AU

 

 

 

 

 

Contact Us

FI

 

 

 

FI => FI (Peppol)

FI => FI (Finvoice)

FI => FI (Try Peppol, otherwise Finvoice)

 

 

 

 

Contact Us

IN

IN => DE

 

 

 

IN => IN (same state)

IN => IN (between states)

 

 

 

Contact Us

JP

 

 

 

 

 

JP => JP

 

 

Contact Us

SA

 

 

 

 

 

 

SA => SA

 

Contact Us

US

 

 

 

 

 

 

 

US => US

Contact Us

World

World => DE

 

 

 

 

 

 

 

Contact Us
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 via the (TEST) Peppol network. 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 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, 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 the Peppol network?

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": []
  }
}

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 should be considered secrets, so do not publish them in 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 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://www.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://www.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://www.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:

    • Peppol

    • Italy SDI (simulated)

    • India GSTIN

    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.

When you are sending, you create the sending LegalEntity and then that same LegalEntity can also receive documents. When you want to set up a legal entity for receiving documents, you create a LegalEntity and then that 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!

3.2.2. Basic Data

If you have a company or integrator account, a LegalEntity can be created in the UI and you can skip to the next section, Identifiers. Otherwise, a LegalEntity is created through the endpoint

Create a new LegalEntity

The party name and a complete address are always required. There are a few special properties that we will discuss here.

advertisements

The advertisements property determines what will be advertised as receivable documents on the various exchange networks, like OpenPeppol. The default is just ["invoice"] which is what you usually want. But if you have implemented the extended webhook events (see Webhooks for Sending) then you will also want to advertise InvoiceResponse and use ["invoice", "invoice_reponse"].

public

This property determines if the LegalEntity details will be published in various directories, such as the Peppol Directory (https://directory.peppol.eu/). Note that for SG:UEN identifiers private identifiers are not allowed, so they will always be advertised on the Peppol network.

tenantId

The tenant_id property is related to the LegalEntity. If you specify it when creating or updating a LegalEntity, this field will be included in any webhooks for that LegalEntity. It can be used to determine which of your tenants the webhook is for and for instance derive a database connection string from it. If you do not have a multi-tenant platform, this field can be ignored.

thirdPartyXxx

These two credential fields are specific only for Indian LegalEntities (and are mandatory for these). These are the credentials for the GSTIN to allow us to obtain the QR-code for the invoice (see Globalization).

rea

The REA details are only for Italian LegalEntities. If your Italian LegalEntity does not have a REA iscrizione, you can leave these out.

3.2.3. 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

To add an identifier, use this endpoint:

Create a new PeppolIdentifier

Note that Singapore has special rules regarding the creation of the SG:UEN identifier for an SG LegalEntity. This process is described here:

SG - Singapore

3.2.4. 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:

  1. Compliance

  2. Receiver-preferred Networks

  3. Exchange Networks

  4. Static Routes

  5. Email

1. Compliance

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

  1. V-flow

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

    ​

  2. Y-flow

    There are two types of Y-flow:

    1. Clearing

      In the clearing 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 placed inside the PDF. We support two models here, one where we send the invoice and the other where you send the invoice. See for example the flow for India:

      ​
      ​

    2. Reporting

      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 Y-flow 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.) ​
​
We also support Y-flows in which, after the necessary work with the tax authority has completed, you are able to retrieve the signed invoice and send it yourself. For this, use the "clearWithoutSending" flag. ​
​
If you provide a PDF, the Y-flow will look for markers in that document to add data from the tax authority. For details, see PDF Stamping.

2. Receiver-preferred Networks

Receiver-preferred networks allow a receiver to receive through a particular network. This only works at the country level. For instance, in Italy, receivers prefer to receive invoices from the SDI network. But a non-Italian sender will typically not be connected to this network. However, through Storecove, this flow is possible. This neutralizes the competitive advantage that Italian suppliers have over non-Italian suppliers due to this receiver preference.

​

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 Peppol and BPC. 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, we will respond with an HTTP 422 Unprocessable Entity with a body "No action taken".

Other Documents Sending Workflow

The sending workflow for non-invoices currently consists of only the Exchange Networks phase.

Exchange Network Discovery

Because of the complexity of the sending flow it is recommended to follow the standard flow and process a possible HTTP 422 response. However, it is also possible to perform a discovery on one or more exchange networks and based on that decide whether or not to send the invoice via the Storecove API. That endpoint is:

Disover Network Participant

It takes one parameter, an DiscoverableParticipant object. This object contains the identifier of the recipient of the document. When you call this endpoint, Storecove will query the relevant exchange networks (e.g. Peppol) to see whether the customer has registered with this network.

A typical response is

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

If the result code is ‘OK’, submit the invoice via the Invoice Submission API call.

The "email" property indicates whether the electronic invoice can be sent via Peppol, but would ultimately received as PDF via email. This could currently only be the case for Belgian receivers. In Belgium, all companies have been registered on the Peppol network by the Belgian Peppol Authority, but if they have not chosen a commercial Peppol service provider, they will only receive a PDF version of the invoice and not your/our electronic invoice. It is up to the receiver to resolve this if they want real electronic invoices, and therefore it is recommended to send via Peppol even if the "email" property is true. Nevertheless, this property does give you the opportunity to send your own email if you prefer that.

3.3.2. Sending a document

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

  1. A JSON object that contains the document data

  2. (only for invoices) A Base64 encoded string 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. We can enable addtional formats on request.

Two document types can currently be sent:

  • Invoice

  • Invoice Reponse

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 does not support self billing, except in AU/NZ. But we do not support it in AU/NZ. Contact us if you require this.

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"
  }
]

The category "export" is important for globalization (see Globalization). When sending between legal territories, use this category, the country of the sender and 0% as a percentage. This way, we will automatically perform any tax conversion that is required for the receiver.

If you are forced to 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
Order

The following gives the maximum JSON object for an order:

Order
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.

3.3.4. Webhooks for Sending

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

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

The following 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).

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.

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, BPC) 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 BPC, 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 BPC 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:ORG

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

BPC

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

FI

B2B

Finvoice

FI:OVT

FI:VAT

FI:OPID

IT

B2B

Peppol

Not allowed

IT

B2G

Peppol

IT:IVA

IT:CUUO

IT

B2B

SDI

IT:IVA, IT:CF

IT:CUUO

IT

B2G

SDI

IT:IVA

IT:CUUO

SE

B2G

Svefaktura

SE:ORGNR

SE:VAT

SE:OPID (optional)

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 BPC.

When agreed between the sender and receiver, it is also possible to use speical 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

In these cases too, the connections are setup one-by-one and cannot benefit from the scalability of exchange networks suchs as Peppol and BPC. 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.

In some cases, only email is available for routing:

Country X2Y Network Receiver Business Identifiers Routing

Legal Identifier

Tax Identifier

Routing Identifier(s)

IN

B2B

India IRP

IN:GSTIN

email[1]

IN

B2C

email[2]

SA

B2B

Storecove/ZATCA

SA:TIN

email[3]

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, BPC, 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, we will send a webhook with the following contents:

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

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

Invoices: Get Purchase invoice data as JSON

Orders: Get a new ReceivedDocument

Use the "document_guid" as the {guid} parameter.

Note that the "received_guid" will be empty unless you used the ReceivedDocuments endpoint to push the received invoice into our API in the first place. So it will always be empty when receiving via exchange networks such as Peppol. If you did use the ReceivedDocuments endpoint and the document failed to be processed correctly, you will receive

{
  "event_type": "received_document",
  "event_group": "unknown",
  "event": "failed",
  "receive_guid": "d9d395f8-771d-4b93-b0a5-11e9a7d7d6f5",
  "document_guid": null,
  "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

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

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.",
  "buyer_reference": "The buyer's reference. Used for internal routing by the receiver.",
  "order_reference": "deprecated, use references",
  "billing_reference": "deprecated, use references",
  "contract_document_reference": "deprecated, use references",
  "project_reference": "deprecated, use references",
  "references": [
    {
      "document_type": "purchase_order",
      "dcument_id": "used to be the order_reference"
    },
    {
      "document_type": "buyer",
      "dcument_id": "used to be the buyer_reference"
    },
    {
      "document_type": "billing",
      "dcument_id": "billing_reference"
    },
    {
      "document_type": "contract",
      "dcument_id": "contract_document_reference"
    },
    {
      "document_type": "project",
      "dcument_id": "used to be the project_reference"
    },
    {
      "document_type": "despatch_advice",
      "dcument_id": "Desptach Advice Reference"
    },
    {
      "document_type": "originator",
      "dcument_id": "Originator Document Reference"
    },
    {
      "document_type": "receipt",
      "dcument_id": "Receipt Document Reference"
    }
  ],
  "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": "NL99ABNA098765432",
      "branche_code": "",
      "payment_id": "AAA333444",
      "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": [
    {
      "line_id": "The ID of the line",
      "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
        }
      ],
      "price": {
        "amount": 10.25,
        "base_quantity": 1.0
      },
      "units": {
        "quantity": 1.0,
        "unit_code": "C62",
      },
      "additional_item_properites": [
        {
          "name": "Key1",
          "value": "Value1. Note that keys can be anything, to be agreed between the sender/receiver."
        },
        {
          "name": "Key2",
          "value": "Value2"
        }
      ],
      "references": [
        {
          "document_type": "purchase_order",
          "document_id": "The purchase order number",
          "line_id": "The purchase order line id",
          "issue_date": "The purchase order issue date"
        },
        {
          "document_type": "line_standard_item_identification",
          "document_id": "standard item identification",
          "document_id_scheme_id": "The scheme for the identification",
          "document_id_scheme_agency_id": "The agency that released the scheme",
          "document_id_scheme_version_id": "The version of the scheme"
        },
        {
          "document_type": "line_sellers_item_identification",
          "document_id": "Seller's item identification"
        },
        {
          "document_type": "line_buyers_item_identification",
          "document_id": "Buyers's item identification"
        },
        {
          "document_type": "item_classification_code",
          "document_id": "The item classification code",
          "document_id_list_id": "The identification scheme identifier",
          "document_id_list_agency_id": "The identification scheme issuing agency identifier",
          "document_id_list_version_id":  "The identification scheme version identifier"
        },
        {
          "document_type": "item_commodity_code",
          "document_id": "The item commodity code",
          "document_id_list_id": "The identification scheme identifier",
          "document_id_list_agency_id": "The identification scheme issuing agency identifier",
          "document_id_list_version_id":  "The identification scheme version identifier"
        },
        {
          "document_type": "line_document_reference",
          "document_id": "The document reference",
          "document_id_list_id": "The identification scheme identifier",
          "document_id_list_agency_id": "The identification scheme issuing agency identifier",
          "document_id_list_version_id":  "The identification scheme version identifier"
        },
      ],
      "amount_excluding_tax": 10.25,
      "tax": {
        "tax_amount": 0.00,
        "percentage": 0.00,
        "country": "US",
        "category": "standard",
        "type": "VAT",
        "category_code": "S",
      },
      "accounting": {
        "code": "code",
        "name": "code description",
        "list": "list of the code",
        "list_version": "list_version"
      }
    }
  ],
  "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,
  },
  "tax_subtotals": [
    {
      "amount_excluding_tax": 0.00,
      "tax": {
        "tax_amount": 0.00,
        "percentage": 0.00,
        "country": "US",
        "category": "standard",
        "type": "VAT"
      }
    }
  ]
}

4. Best Practices

4.1. Job Queues

The Storecove API is highly available. However, that does not mean 100%. No one can ever guarantee that.

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.

4.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.

4.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

  • 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.

5. API Reference

5.1. Resources

5.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
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
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)
Responses
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)
Responses
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
Responses
HTTP Code Description Schema

200

Success

AdditionalTaxIdentifier

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content

5.1.2. 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
Responses
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
Disover Network Participant
POST /discovery/receives
Description

Discover a network participant and capabilities.

Parameters
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
Consumes

  • application/json

5.1.3. DocumentSubmissions

Submit a new document.
POST /document_submissions
Description

Submit a document for delivery. This endpoint will replaces the /invoice_submissions endpoint which will soon be deprecated.

Parameters
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
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

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
Consumes

  • application/json

5.1.4. 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

5.1.5. 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

5.1.6. PurchaseInvoices

Get Purchase invoice data as JSON
GET /purchase_invoices/{guid}
Description

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

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"
Responses
HTTP Code Description Schema

200

Success

PurchaseInvoice

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content
Get Purchase invoice data in a selectable format
GET /purchase_invoices/{guid}/{packaging}
Description

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.

enum (json, ubl, original)

"json"

Query

pmv
optional

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"
Responses
HTTP Code Description Schema

200

Success

PurchaseInvoiceUbl

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content
Get Purchase invoice data as JSON with a Base64-encoded UBL string in the specified version
GET /purchase_invoices/{guid}/{packaging}/{package_version}
Description

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

5.1.7. ReceivedDocuments

Receive a new Document
POST /legal_entities/{legal_entity_id}/received_documents
Description

Receive a new Document.

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

EXPERIMENTAL: use only for orders. Get a new ReceivedDocument.

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"
Responses
HTTP Code Description Schema

200

Success

ReceivedDocument

401

Unauthorized

No Content

403

Forbidden

No Content

404

Not Found

No Content
Consumes

  • application/json

5.1.8. 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

5.2. Definitions

5.2.1. AccountingCustomerParty

The customer receiving the document.

Name Description Schema

party
required

ReceiverParty

publicIdentifiers
optional

A list of legal and tax identifiers for this customer.

< PublicIdentifier > array

5.2.2. AccountingSupplierParty

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

Name Schema

party
optional

SenderParty

5.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

5.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

5.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

5.2.6. AdditionalTaxIdentifierUpdate

Name Description Schema

identifier
required

The identifier.

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

5.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

5.2.8. AllowanceCharge

Name Description Schema

amountExcludingTax
optional

The amount for the allowance or charge, excluding tax.

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

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

5.2.9. 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. Currently only application/pdf is allowed.

enum (application/pdf)

primaryImage
optional

Whether or not this document is a visual representation of the invoice data. Note that although this property is not yet deprecated, 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

5.2.10. 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

5.2.11. 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)

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)

5.2.12. 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

flow_type
required

The CorpPass flow type.

enum (corppass_flow_redirect, corppass_flow_email)

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

5.2.13. 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, XI, YE, YT, ZA, ZM, ZW)

5.2.14. 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

5.2.15. 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)

5.2.16. CountrySpecifications

Name Schema

countries
optional

< CountrySpecification > array

5.2.17. 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, BYR, 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, MRO, 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, STD, 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)

5.2.18. Delivery

Name Description Schema

actualDate
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. Used only for DocumentOrder.

DeliveryParty

deliveryPartyName
optional

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

shippingMarks
optional

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

schemeId
optional

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

string

5.2.19. 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

5.2.20. 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

5.2.21. 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

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

5.2.22. 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

5.2.23. 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)

5.2.24. 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 10MB after Base64 encoding.

< Attachment > array

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±zzzz
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

5.2.25. DocumentSubmission

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

Name Description Schema

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

5.2.26. 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

network
optional

The exchange network that was used to send the document

enum (as2, email, peppol, sdi)

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

5.2.27. 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)

5.2.28. DocumentSubmissionEvidenceEvidence

Name Description Schema

message_id
optional

The unique message id used in the OpenPeppol SBDH.

string

receiving_accesspoint
optional

An identification of the OpenPeppol accesspoint that the invoice was sent to.

string

remote_mta_ip
optional

The IP address of the sending SMTP server.

string

reporting_mta
optional

An identification for the sending SMTP.

string

smtp_response
optional

The response of the receiving SMTP server.

string

timestamp
optional

The timestamp of the delivery to the receiving SMTP server.

string

transmission_id
optional

The unique id for this OpenPeppol transmission.

string

xml
optional

The XML evidence for the transmission. This is the XML returned by the receiving OpenPeppol accesspoint.

string

5.2.29. DocumentSubmissionResult

The result of a document submission

Name Description Schema

guid
optional

A (V4) GUID for the document submission

string

5.2.30. EIdentifiers

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

Type : < RoutingIdentifier > array

5.2.31. ErrorModel

Name Schema

details
optional

string

source
optional

string

5.2.32. 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

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

accountingCustomerParty
required

The party the invoice is sent to.

AccountingCustomerParty

accountingSupplierParty
optional

The party sending the invoice. Most data for the AccountingSupplierParty 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 an invoice-by-invoice basis. Contact us if you want to use this feature.

AccountingSupplierParty

allowanceCharges
optional

An array of allowance charges.

< AllowanceCharge > array

amountIncludingVat
required

amountIncludingVat is important because of rounding differences. In many invoices, the sum of the line item amounts excluding VAT and the VAT amounts is not equal to first summing the line items without VAT, and then applying VAT. The difference is automatically calculated and included in the electronic invoice, so the receiving accounting package can process the electronic invoice without problems.

number

attachments
optional

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

< Attachment > array

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.
Default : false

boolean

delivery
optional

The delivery of the invoice.

Delivery

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

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

note
optional

A note to add to the invoice

string

paymentMeansArray
optional

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

< PaymentMeans > array

paymentTerms
optional

The payment terms of the invoice.

PaymentTerms

preferredInvoiceType
optional

In auto mode, the choice between invoice or creditnote 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.
Default : "prefer_autodetect"

enum (prefer_autodetect, prefer_invoice, prefer_creditnote)

prepaidAmount
optional

The amount already 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 "x2y": "b2c", sender countries ES, IT and PT, "clearWithoutSending": true and "taxSystem": "tax_line_percentages"
Default : "price_mode_net"

enum (price_mode_net, price_mode_gross)

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 support all documentTypes.

< Reference > array

selfBillingMode
optional

In self billing mode, the AccountingCustomerParty and the AccountingSupplierParty are be switched. Such an invoice can only be sent via email. Also, your account will need to allow the use of this mode, so before trying to use this please first contact Storecove.
Default : false

boolean

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

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

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.
Default : "b2b"

enum (b2b, b2g, b2c, b2b_sez)

5.2.33. InvoiceData

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

Name Description Schema

conversionStrategy