Invoices

Invoices are statements of amounts payed for by a customer. They consist of multiple Invoice Items and are usually created when a Transaction completes.

The invoice object

The invoice of the transaction

Required attributes

Name
_id
Type
string
Description
The ID of the invoice.
Name
sellerId
Type
string
Description
The ID of the seller associated with the invoice.
Name
recipient
Type
object
Description
Information on the recipient of the invoice.
Required nested attributes (3)
Name
name
Type
string
Description
The name of the recipient.
Name
firstname
Type
string
Description
The first name of the recipient.
Name
lastname
Type
string
Description
The last name of the recipient.
Optional nested attributes (2)
Name
company
Type
string
Description
The company name of the recipient.
Name
address
Type
object
Description
The address of the recipient.
Optional nested attributes (7)
Name
fullAddress
Type
string
Description
Optional full address
Name
street
Type
string
Description
The street of the address. Street name including number.
Name
line2
Type
string
Description
The additional field of the address.
Name
postal
Type
string
Description
The postal code of the address.
Name
city
Type
string
Description
The city of the address.
Name
country
Type
string
Description
The country of the address. An ISO 3166 country code.
Name
state
Type
string
Description
The state of the address. If applicable
Name
counter
Type
number
Description
The counter used to create no.
Name
no
Type
string
Description
A unique number for the invoice consisting of the creation date and an increasing counter.
Name
items
Type
array<object>
Description
An array of invoice items.
Required nested attributes (6)
Name
title
Type
string
Description
The title of the invoice item.
Name
amount
Type
number
Description
The amount of the invoice item.
Name
total
Type
number
Description
The total of the invoice item.
Name
regularTotal
Type
number
Description
The non-discounted total of the invoice item.
Name
includedTax
Type
number
Description
The total of taxes included in the invoice item.
Name
taxRate
Type
number
Description
The tax rate applied on the invoice item.
Optional nested attributes (1)
Name
type
Type
enum(product, ticket, fulfillment, outerCharge, discount, voucher, bundle, additionalFee, insurance)
Description
The type of the invoice item.
Name
currency
Type
enum(EUR, USD, GBP, AUD, CHF, THB, ILS, COP, MXN, DKK, NOK, SEK, QAR, CAD, ISK, GTQ, INR, DOP, SGD, PLN, SAR, TTD, ZAR, KYD, HKD, CZK, KRW, JPY, NZD, AED, MAD, TWD, BRL, BWP, NAD, KES, SCR, TRY, SZL, LSL, TZS, UGX, ZMW, ZWG, GHS, NGN, SLE, LRD, XOF, XAF, GEL, IDR, ARS, CRC, HUF, EGP, MYR, VND, PHP)
Description
An ISO 4217 3-character code of the currency.

Optional attributes

Name
type
Type
enum(invoice, cancellation)
Description
The type of the invoice.
Name
transactionId
Type
string
Description
The ID of the transaction the invoice originated from.
Name
cancellationId
Type
string
Description
The ID of the associated cancellation.
Name
components
Type
array<object>
Description
An array of exposed price components.
Optional nested attributes (2)
Name
name
Type
string
Description
Name
total
Type
number
Description
Name
total
Type
number
Description
The invoice total after discounts and taxes.
Name
discountSum
Type
number
Description
The total of all discounts applied.
Name
detailsPerRate
Type
array<object>
Description
The tax details grouped by tax rates.
Required nested attributes (3)
Name
taxRate
Type
number
Description
The applied tax rate.
Name
includedTax
Type
number
Description
The total of taxes associated with the tax rate.
Name
reducedTax
Type
number
Description
The tax reduction through applied discounts.
Name
taxItems
Type
array<object>
Description
An array of tax items.
Required nested attributes (3)
Name
rate
Type
number
Description
Name
perUnit
Type
number
Description
Name
total
Type
number
Description
Optional nested attributes (6)
Name
name
Type
string
Description
Name
taxTypeId
Type
string
Description
Name
netTotal
Type
number
Description
Name
netPerUnit
Type
number
Description
Name
taxPayableAccountId
Type
string
Description
Name
taxPayableAccountCode
Type
string
Description
Name
includedTax
Type
number
Description
The total of all taxes included.
Name
taxRate
Type
number
Description
The default tax rate applied on items.
Name
includedOuterChargeTax
Type
number
Description
The total of all taxes on included outer charges.
Name
outerChargeTaxRate
Type
number
Description
The tax rate applied on outer charges.
Name
origin
Type
enum(onlinesale, pos)
Description
Whether the invoice has been created through an online or offline transaction.
Name
extraFields
Type
object
Description
The extra fields of the invoice.
Name
secret
Type
string
Description
The secret of the invoice.
Name
referenceInvoiceId
Type
string
Description
The reference invoice which the invoice evolved from.
Name
footerText
Type
array<string>
Description
The custom footer columns of the invoice.
Name
createdAt
Type
string
Description
An ISO Timestamp indicating when the invoice was created.
Name
updatedAt
Type
string
Description
An ISO Timestamp indicating when the invoice was last updated.

Example

{
  "_id": "507f191e810c19729de860ea",
  "sellerId": "507f191e810c19729de860ea",
  "recipient": {
    "name": "Example Name",
    "firstname": "string",
    "lastname": "string",
    "company": "string",
    "address": {
      "fullAddress": "string",
      "street": "string",
      "line2": "string",
      "postal": "string",
      "city": "string",
      "country": "string",
      "state": "string"
    }
  },
  "counter": 10.5,
  "no": "string",
  "items": [
    {
      "title": "string",
      "amount": 10.5,
      "total": 10.5,
      "regularTotal": 10.5,
      "includedTax": 10.5,
      "taxRate": 10.5,
      "type": "product"
    }
  ],
  "currency": "EUR",
  "type": "invoice",
  "transactionId": "507f191e810c19729de860ea",
  "cancellationId": "507f191e810c19729de860ea",
  "components": [
    {
      "name": "Example Name",
      "total": 10.5
    }
  ],
  "total": 10.5,
  "discountSum": 10.5,
  "detailsPerRate": [
    {
      "taxRate": 10.5,
      "includedTax": 10.5,
      "reducedTax": 10.5
    }
  ],
  "taxItems": [
    {
      "rate": 10.5,
      "perUnit": 10.5,
      "total": 10.5,
      "name": "Example Name",
      "taxTypeId": "507f191e810c19729de860ea",
      "netTotal": 10.5,
      "netPerUnit": 10.5,
      "taxPayableAccountId": "507f191e810c19729de860ea",
      "taxPayableAccountCode": "string"
    }
  ],
  "includedTax": 10.5,
  "taxRate": 10.5,
  "includedOuterChargeTax": 10.5,
  "outerChargeTaxRate": 10.5,
  "origin": "onlinesale",
  "extraFields": {},
  "secret": "string",
  "referenceInvoiceId": "507f191e810c19729de860ea",
  "footerText": [
    "string"
  ],
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z"
}

POST/api/invoices

Create Invoice for Transaction

Payload

Required attributes

Name
transactionId
Type
string
Description
The ID of the transaction.

Request

POST

/api/invoices

const response = await fetch('https://vivenu.com/api/invoices', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer {token}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(  {
    "transactionId": "507f191e810c19729de860ea"
  }),
})

const data = await response.json()

Response (201)

{
  "_id": "507f191e810c19729de860ea",
  "sellerId": "507f191e810c19729de860ea",
  "recipient": {
    "name": "Example Name",
    "firstname": "string",
    "lastname": "string",
    "company": "string",
    "address": {
      "fullAddress": "string",
      "street": "string",
      "line2": "string",
      "postal": "string",
      "city": "string",
      "country": "string",
      "state": "string"
    }
  },
  "counter": 10.5,
  "no": "string",
  "items": [
    {
      "title": "string",
      "amount": 10.5,
      "total": 10.5,
      "regularTotal": 10.5,
      "includedTax": 10.5,
      "taxRate": 10.5,
      "type": "product"
    }
  ],
  "currency": "EUR",
  "type": "invoice",
  "transactionId": "507f191e810c19729de860ea",
  "cancellationId": "507f191e810c19729de860ea",
  "components": [
    {
      "name": "Example Name",
      "total": 10.5
    }
  ],
  "total": 10.5,
  "discountSum": 10.5,
  "detailsPerRate": [
    {
      "taxRate": 10.5,
      "includedTax": 10.5,
      "reducedTax": 10.5
    }
  ],
  "taxItems": [
    {
      "rate": 10.5,
      "perUnit": 10.5,
      "total": 10.5,
      "name": "Example Name",
      "taxTypeId": "507f191e810c19729de860ea",
      "netTotal": 10.5,
      "netPerUnit": 10.5,
      "taxPayableAccountId": "507f191e810c19729de860ea",
      "taxPayableAccountCode": "string"
    }
  ],
  "includedTax": 10.5,
  "taxRate": 10.5,
  "includedOuterChargeTax": 10.5,
  "outerChargeTaxRate": 10.5,
  "origin": "onlinesale",
  "extraFields": {},
  "secret": "string",
  "referenceInvoiceId": "507f191e810c19729de860ea",
  "footerText": [
    "string"
  ],
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z"
}

GET/api/invoices/:id

Get an Invoice

Request

GET

/api/invoices/:id

const response = await fetch('https://vivenu.com/api/invoices/507f191e810c19729de860ea', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "sellerId": "507f191e810c19729de860ea",
  "recipient": {
    "name": "Example Name",
    "firstname": "string",
    "lastname": "string",
    "company": "string",
    "address": {
      "fullAddress": "string",
      "street": "string",
      "line2": "string",
      "postal": "string",
      "city": "string",
      "country": "string",
      "state": "string"
    }
  },
  "counter": 10.5,
  "no": "string",
  "items": [
    {
      "title": "string",
      "amount": 10.5,
      "total": 10.5,
      "regularTotal": 10.5,
      "includedTax": 10.5,
      "taxRate": 10.5,
      "type": "product"
    }
  ],
  "currency": "EUR",
  "type": "invoice",
  "transactionId": "507f191e810c19729de860ea",
  "cancellationId": "507f191e810c19729de860ea",
  "components": [
    {
      "name": "Example Name",
      "total": 10.5
    }
  ],
  "total": 10.5,
  "discountSum": 10.5,
  "detailsPerRate": [
    {
      "taxRate": 10.5,
      "includedTax": 10.5,
      "reducedTax": 10.5
    }
  ],
  "taxItems": [
    {
      "rate": 10.5,
      "perUnit": 10.5,
      "total": 10.5,
      "name": "Example Name",
      "taxTypeId": "507f191e810c19729de860ea",
      "netTotal": 10.5,
      "netPerUnit": 10.5,
      "taxPayableAccountId": "507f191e810c19729de860ea",
      "taxPayableAccountCode": "string"
    }
  ],
  "includedTax": 10.5,
  "taxRate": 10.5,
  "includedOuterChargeTax": 10.5,
  "outerChargeTaxRate": 10.5,
  "origin": "onlinesale",
  "extraFields": {},
  "secret": "string",
  "referenceInvoiceId": "507f191e810c19729de860ea",
  "footerText": [
    "string"
  ],
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z"
}

PUT/api/invoices/:id

Update an Invoice

Payload

Required attributes

Name
mode
Type
enum(update, reissue)
Description
The mode for editing the invoice

Optional attributes

Name
recipient
Type
object
Description
Information on the recipient of the invoice.
Required nested attributes (3)
Name
name
Type
string
Description
The name of the recipient.
Name
firstname
Type
string
Description
The first name of the recipient.
Name
lastname
Type
string
Description
The last name of the recipient.
Optional nested attributes (2)
Name
company
Type
string
Description
The company name of the recipient.
Name
address
Type
object
Description
The address of the recipient.
Optional nested attributes (7)
Name
fullAddress
Type
string
Description
Optional full address
Name
street
Type
string
Description
The street of the address. Street name including number.
Name
line2
Type
string
Description
The additional field of the address.
Name
postal
Type
string
Description
The postal code of the address.
Name
city
Type
string
Description
The city of the address.
Name
country
Type
string
Description
The country of the address. An ISO 3166 country code.
Name
state
Type
string
Description
The state of the address. If applicable
Name
extraFields
Type
object
Description
The extra fields of the invoice.

Request

PUT

/api/invoices/:id

const response = await fetch('https://vivenu.com/api/invoices/507f191e810c19729de860ea', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer {token}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(  {
    "mode": "update",
    "recipient": {
      "name": "Example Name",
      "firstname": "string",
      "lastname": "string",
      "company": "string",
      "address": {
        "fullAddress": "string",
        "street": "string",
        "line2": "string",
        "postal": "string",
        "city": "string",
        "country": "string",
        "state": "string"
      }
    },
    "extraFields": {}
  }),
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "sellerId": "507f191e810c19729de860ea",
  "recipient": {
    "name": "Example Name",
    "firstname": "string",
    "lastname": "string",
    "company": "string",
    "address": {
      "fullAddress": "string",
      "street": "string",
      "line2": "string",
      "postal": "string",
      "city": "string",
      "country": "string",
      "state": "string"
    }
  },
  "counter": 10.5,
  "no": "string",
  "items": [
    {
      "title": "string",
      "amount": 10.5,
      "total": 10.5,
      "regularTotal": 10.5,
      "includedTax": 10.5,
      "taxRate": 10.5,
      "type": "product"
    }
  ],
  "currency": "EUR",
  "type": "invoice",
  "transactionId": "507f191e810c19729de860ea",
  "cancellationId": "507f191e810c19729de860ea",
  "components": [
    {
      "name": "Example Name",
      "total": 10.5
    }
  ],
  "total": 10.5,
  "discountSum": 10.5,
  "detailsPerRate": [
    {
      "taxRate": 10.5,
      "includedTax": 10.5,
      "reducedTax": 10.5
    }
  ],
  "taxItems": [
    {
      "rate": 10.5,
      "perUnit": 10.5,
      "total": 10.5,
      "name": "Example Name",
      "taxTypeId": "507f191e810c19729de860ea",
      "netTotal": 10.5,
      "netPerUnit": 10.5,
      "taxPayableAccountId": "507f191e810c19729de860ea",
      "taxPayableAccountCode": "string"
    }
  ],
  "includedTax": 10.5,
  "taxRate": 10.5,
  "includedOuterChargeTax": 10.5,
  "outerChargeTaxRate": 10.5,
  "origin": "onlinesale",
  "extraFields": {},
  "secret": "string",
  "referenceInvoiceId": "507f191e810c19729de860ea",
  "footerText": [
    "string"
  ],
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z"
}

GET/api/invoices

Get All Invoices

Query parameters

Optional query parameters

Name
top
Type
number
Description
Name
skip
Type
number
Description
Name
transactionId
Type
string
Description
Name
no
Type
string
Description
Name
createdAt
Type
object
Description
Name
type
Type
array<enum(invoice, cancellation)>
Description

Request

GET

/api/invoices

const response = await fetch('https://vivenu.com/api/invoices?top=10.5&skip=10.5&transactionId=507f191e810c19729de860ea&no=value&createdAt=value&type=value1%2Cvalue2', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

{
  "rows": [],
  "total": 1
}

GETPUBLIC/api/public/invoices/info

Get Public Invoice for Transaction

Query parameters

Required query parameters

Name
transactionId
Type
string
Description
Name
secret
Type
string
Description

Optional query parameters

Name
latest
Type
boolean
Description

Request

GET

/api/public/invoices/info

const response = await fetch('https://vivenu.com/api/public/invoices/info?transactionId=507f191e810c19729de860ea&secret=value&latest=true', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

{
  "timezone": "Europe/Amsterdam",
  "seller": {
    "_id": "507f191e810c19729de860ea",
    "name": "Example Name",
    "image": "string",
    "city": "string",
    "documentSettings": {
      "image": "string",
      "invoice": {
        "footerColumns": [
          {
            "text": "string",
            "active": true
          }
        ]
      }
    },
    "street": "string",
    "postal": "string",
    "locationName": "string",
    "country": "string",
    "taxRate": 0.19,
    "taxNo": "string",
    "localTaxName": "string"
  },
  "customPaymentMethod": []
}