On this page

Invoice OMP API

Invoice API for online marketplaces generates invoices for over 100 countries. Learn information on elements of the invoice API, including line items, discounts, and exemptions.

The following documentation covers the information on elements of the invoice OMP API, including requests, responses, and error codes.

We don’t store any of your invoice data.

To integrate invoice OMP API:

  1. Register a Lovat Account.
  2. Fill a company profile.
  3. Choose a plan.
  4. Set up Webhooks.
  5. Get a token.

API Reference

Lovat API uses the REST architecture.  The API has predictable, resource-oriented URLs and uses HTTP response codes to indicate API errors. The API always responds in the JSON format, including cases of errors.

Authentication

Authentication to the invoice OMP API is performed via HTTP header basic authentication. Subscribers need to provide a token as the basic authentication value. If you’re new to Lovat, you’ll need to sign up for an account to get your API key.  The API uses built-in HTTP features such as HTTP authentication and HTTP verbs, which can be interpreted by off-the-shelf HTTP clients. It also supports cross-origin resource sharing, allowing you to access it securely from a client web application.

POST

URL

Lovat API uses the following endpoint paths:
Production Region

https://omp.vatcompliance.co/api/omp/omp_invoice  — OMP invoice API

Test Region

sandbox.vatcompliance.co/api/omp/omp_invoice/{access_token}

POST

Method

The request type: POST

https://omp.vatcompliance.co/api/omp/omp_invoice/{access_token}

JSON Params

Parameter Type Description Required
invoice_ID String Maximum 25 characters Required
marketplace_establishment_country_id String OMP establishment country. Three-letter uppercase country code per ISO 3166-1 alpha-3 Required
vendor_establishment_country_id String Merchant establishment country. Three-letter
uppercase country code per ISO 3166-1 alpha-3		 Required
marketplace_IOSS_number Boolean For EU orders only. True – OMP has IOSS VAT number Optional
order_currency String Transaction currency. Three-letter currency code per
ISO 4217		 Required
order_date String Absence of transaction date considered as current date. Date of the transaction in accordance with ISO 8601 Optional
order_amount Float Total amount of the order, including shipping Required
shipping_fee Float Total amount of shipping for the order Optional
arrival_country String A country where the order shipped to. Three-letter uppercase country code per ISO 3166-1 alpha-3 Required
arrival_zip String Required for US orders: Postal code where the order shipped to Optional
arrival_state String For US, Canada, UK: Two-letter ISO state code where
the order shipped to		 Optional
departure_country String

Three-letter ISO country code of the country where
the order shipped from. All countries are specified as strings according to ISO 3166- 1 alpha-3

 Required
departure_zip String For US orders: Postal code where the order
shipped from		 Optional
departure_state String

For US, Canada, UK: 

Two-letter ISO state code where the order
shipped from

 Optional
item_code String Required for digitally supplied services.
Tax categories of digital services		 Optional
item_price Float Item price Optional
item_quantity Float Quantity of an items Optional
good_code String HS good code of an item according to EU’s eight-digit coding system The Combined Nomenclature (CN) Ooptional
vat_number_of_customer String Tax  number of buyer Optional
exemption_type Enum For US orders only. Types used: wholesale, government, educational, marketplace, other, or non_exempt Optional
marketplace_nexus_state String OMP nexus states. Two-letter ISO state codes where the marketplace has nexus Optional

 

POST

Request and Response

sent over HTTPS, use TLS 1.2 or higher, contain authentication parameters.

Request Examples

Command Line

/curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' 
-d '{ 
   "invoice_id": "ttt4565-85546",
   "OMP_establishment_country_id": "GBR",
   "merchant_establishment_country_id": "DEU",
   "OMP_IOSS_number": true,
   "order_ammount": 43.04,
   "shipping_fee": 2.3,
   "order_currency": "EUR",
   "arrival_country" : "LVA",
   "good_code": "62160000",
   "departure_country" : "AUS"
 }' 
'https://omp.vatcompliance.co/api/omp/omp_invoice/6cec387781a94425b401206d1710801a
{ 
   "invoice_id": "0099990100",
   "marketplace_establishment_country_id": "GBR",
   "vendor_establishment_country_id": "GBR",
   "marketplace_IOSS_number": "True",
   "order_date": "2022-01-09",
   "order_amount": 120.50,
   "shipping_fee": 2.30,
   "order_currency": "GBP",
   "arrival_country" : "DEU",
   "departure_country" : "GBR",
   "Item":[ 
{"item_code": “1”,item_price”: “51”, “item_quantity”: “1”, "good_code": "62160000"},
{"item_code": “2”,item_price”: ”67.20”, “item_quantity”: “1”, "good_code": "62380000"}
   ]
}
{ 
   "invoice_id": "0099990099",
   "marketplace_establishment_country_id": "DEU",
   "vendor_establishment_country_id": "POL",
   "marketplace_IOSS_number": "False",
   "order_amount": 1120.50,
   "order_currency": "EUR",
   "departure_country" : "POL",
   "arrival_country" : "LVA",
   "vat_number_of_customer": "LV9875234",
 }/

Example Success Response

Command Line

/{
  "invoice_id": "ttt4565-85546",
  "invoice_parties":  “vendor_customer”,
  "invoice_type":  “VAT_invoice”,
  "tax_type": "VAT",
  "taxable_jurisdiction": "DEU",
  "vat_percent":  19,
}
{
  "invoice_id": "0099990107",
  "invoice":[ 
{
  "invoice_code": "1", 
  "invoice_parties":  “vendor_marketplace”, 
    "invoice_type":  “VAT_invoice”,
     "tax_type": "VAT",
     "taxable_jurisdiction": "FRA",
     "vat_percent":  0
},
{
  "invoice_code": "2",
  "invoice_parties":  “marketplace_customer”,
     "invoice_type":  “VAT_invoice”,
     "tax_type": "VAT",
     "taxable_jurisdiction": "ITA",
     "vat_percent":  22
}
  ]
}
{
  "invoice_id": "0099990102",
  "invoice_parties":  “vendor_customer”,
  "invoice_type":  “commercial_invoice”,
  "tax_type": "VAT",
  "taxable_jurisdiction": "DEU",
  "vat_percent":  19,
  "intrinsic_value":  113.80,
  "intrinsic_value_currency": “EUR”
}/

Errors List

List of supported HTTP errors:

200, 201, 204
No errors

400 Bad Request
This often indicates a required parameter missing. Refer to the response body for details

401 Unauthorized
No valid API key provided

402 Request Failed
Request failed despite valid parameters

403 Forbidden
No permission. Refer to the response body for details

404 Not Found
The requested item doesn’t exist

409, 422
Invalid request parameters

412 Precondition Failed
The project has not been activated yet (used in the Get Token method)

415 Unsupported Media Type
‘Content-Type: application/json’ missing in HTTP header

500, 502, 503, 504 Server Errors 
Something went wrong

Date format

All dates are specified as strings according to ISO 8601 (e.g., 2021-01-15).

Countries

Lovat API is supported in over 100 countries. You can find the list of these countries on our website.

Invoice categories

VAT invoice 1
Sales tax invoice 2
Reverse charge invoice 4
Commercial invoice 4
Exempted invoice 5

Call Limiting

We limit API requests to 100 per minute for Standard OMP plans. Our Advanced and Enterprise plans include an increased limit of 1,000 per minute. You may have more calls than your monthly plan limit. Overage fees are charged separately if you exceed your plan limit during a next month.

Exemption Types

For US orders only types of exemption: wholesale, government, marketplace, other, non_exempt, or nill.

PUT

Referrer URL

The method is available at the following URL:

Command Line

{
  "invoice_id": "ttt4565-85546",
  "invoice_parties":  “vendor_customer”,
  "invoice_type":  “VAT_invoice”,
  "tax_type": "VAT",
  "taxable_jurisdiction": "DEU",
  "vat_percent":  19,
}
{
  "invoice_id": "0099990107",
  "invoice":[ 
{
  "invoice_code": "1", 
  "invoice_parties":  “vendor_marketplace”, 
    "invoice_type":  “VAT_invoice”,
     "tax_type": "VAT",
     "taxable_jurisdiction": "FRA",
     "vat_percent":  0
},
{
  "invoice_code": "2",
  "invoice_parties":  “marketplace_customer”,
     "invoice_type":  “VAT_invoice”,
     "tax_type": "VAT",
     "taxable_jurisdiction": "ITA",
     "vat_percent":  22
}
  ]
}
{
  "invoice_id": "0099990102",
  "invoice_parties":  “vendor_customer”,
  "invoice_type":  “commercial_invoice”,
  "tax_type": "VAT",
  "taxable_jurisdiction": "DEU",
  "vat_percent":  19,
  "intrinsic_value":  113.80,
  "intrinsic_value_currency": “EUR”
}