NAV Navbar
shell javascript php

Introduction

Welcome to Space Invoices API

Space Invoices (SI) is a developer-oriented invoicing API. You can use it to create and manage invoices and various other types of documents, to save time, money and resources, and also to help you refine your commercial software. Furthermore, SI facilitates your management of the data within these documents.

To understand the full scope of our API, please start by taking a look at our documentation. Welcome!

Visit our website at spaceinvoices.com and sign up for an account.

Getting help

We're excited to have you on board and we're here to help you elevate your software solution by being your invoicing API of choice. Always looking to make SI better, let us know if you have a specific challenge you'd like us to help you tackle. Find us at our community Gitter channel: See you soon!

Join our Gitter here.

About

While the API is fully operational and used in production by thousands of organizations every month, we always strive to improve its features. For this reason, we continuously work to update the finer details of this documentation. Features are added regularly, so do check back for updates or sign up for our product update email on our website. We're happy to have you with us, and we look forward to seeing what you can make!

Getting started

To create your first invoice:

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/documents" \
  -H "Authorization: LAUNCH_CODE" \
  -d _documentClient[name]="Rocket Man" \
  -d _documentClient[country]="United Kingdom" \
  -d _documentItems[0][name]="Space suit" \
  -d _documentItems[0][quantity]=2 \
  -d _documentItems[0][unit]="Item" \
  -d _documentItems[0][price]="1000" \
  -d _documentItems[0][_documentItemTaxes][0][rate]=21

To download a PDF of the created invoice

curl "https://api.spaceinvoices.com/v1/documents/DOCUMENT_ID/pdf?l=en" \
  -H "Authorization: LAUNCH_CODE" \
  -o my-first-invoice.pdf

Here are some recommended steps to successfully venture into the invoicing universe.

1. Create an Account on Space Invoices

Signup for an account if you haven't already, you'll need it to start making API calls.

It's also recommended to log into Space Invoices as your launch code (access token) will be automatically populated in all documentation examples.


2. Create an Organization

Organizations are the central unit of all other resources in the API, you'll need one to issue invoices.

Space Invoices supports multi-tenant management, meaning an account can have multiple organizations linked to it, each one represents a legal entity like a business, NGO, club, and similar.


3. Create your first invoice

On the right is an API call to create a simple invoice, take it for a spin.

If you're logged into Space Invoices your launch code and organization's ID should already be populated in the example.


4. Fetch a PDF of the invoice you just created

Now let's use the next command to fetch a PDF the invoice, this time you'll need to replace the DOCUMENT_ID in the URL with the actual ID of the created invoice.


5. That's it

Great, you now know how to issue invoices!


You can also create and manage organizations for your end customers and issue invoices in their name:

Authentication

To make calls to the API, ensure you have inserted your launch code:
Space Invoices uses launch codes to allow access to the API. A launch code can be acquired from our developer dashboard Mission Control or by logging in through the API.

# With shell, you can just pass the correct header with each request
curl "https://api.spaceinvoices.com/v1/..."
  -H "Authorization: LAUNCH_CODE"
var spaceInvoices = new SpaceInvoices("LAUNCH_CODE");
<?php
  Spaceinvoices\Spaceinvoices::setAccessToken("LAUNCH_CODE");
?>

Space Invoices uses launch codes to allow access to the API. A launch code can be acquired from our developer dashboard Mission Control.

In headers

The launch code has to be included in all API requests to the server in a header like the following:

Authorization: LAUNCH_CODE

In query params

Alternatively, the launch code can be added as a query parameter of the URL.
Please note this implementation has considerable security risks!

?access_token=LAUNCH_CODE

In documentation

If you are logged into Mission Control the documentation examples will already contain your real launch code.
We recommend creating a non-expiring one through Mission Control for production use.

Errors

Space Invoices API uses the following error codes:

400 Bad Request
Your request is invalid.

401 Unauthorized
You do not have the permission to access the route or are not authorized for the resource with the given ID.

404 Not Found
The specified route could not be found.

422 Unprecessable entity
The provided data is invalid, usually manifesting due to a validation error. Details about the error are visible in the server response body.

500 Internal Server Error
We had a problem with our server. Try again later. This is very rate.

503 Service Unavailable
We're temporarily offline for maintenance. Please try again later. This is very rare.

Filters

Filters

# Where
curl "...?filter[where][type]=invoice"
# or
curl "...?filter[where][type][inq]=invoice"

# Include
curl "...?filter[include]=payments"
# or
curl "...?filter[include][tax]=taxRate"

# Fields
curl "...?filter[fields][type]=true"

# Limit
curl "...?filter[limit]=5"

# Order
curl "...?filter[order][date]=ASC"

# Skip
curl "...?filter[skip]=5"

# Deleted
curl "...?filter[deleted]=true"
// Where
var queryParams = {
  filter: {
    where: {
      type: "invoice",
    },
  },
};
// or
var queryParams = {
  filter: {
    where: {
      type: {
        inq: ["invoice", "advance"],
      },
    },
  },
};

// Include
var queryParams = {
  filter: {
    include: "payments",
  },
};
// or
var queryParams = {
  filter: {
    include: {
      tax: "taxRate",
    },
  },
};

// Fields
var queryParams = {
  filter: {
    fields: {
      type: true,
    },
  },
};

// Limit
var queryParams = {
  filter: {
    limit: 5,
  },
};

// Order
var queryParams = {
  filter: {
    order: {
      date: "ASC",
    },
  },
};

// Skip
var queryParams = {
  filter: {
    skip: 5,
  },
};

// Deleted
var queryParams = {
  filter: {
    deleted: true,
  },
};
<?php
  // Where
  $queryParams = array(
    "filter" => array(
      "where" => array(
        "type" => "invoice"
      )
    )
  );

  // or
  $queryParams = array(
    "filter" => array(
      "where" => array(
        "type" => array(
          "inq" => [
            "invoice",
            "advance"
          ]
        )
      )
    )
  );

  // Include
  $queryParams = array(
    "filter" => array(
      "include" => "payments"
  );

  // or
  $queryParams = array(
    "filter" => array(
      "include" => array(
        "tax" => "taxRate"
      )
    )
  );

  // Fields
  $queryParams = array(
    "filter" => array(
      "fields" => array(
        "type" => true
      )
    )
  );

  // Limit
  $queryParams = array(
    "filter" => array(
      "limit" => 5
    )
  );

  // Order
  $queryParams = array(
    "filter" => array(
      "order" => array(
        "date" => "ASC"
      )
    )
  );

  // Skip
  $queryParams = array(
    "filter" => array(
      "skip" => 5
    )
  );

  // Deleted
  $queryParams = array(
    "filter" => array(
      "deleted" => true
    )
  );
?>

Space Invoices API uses a filtering mechanism to control how the data is queried.

where Where query filter.
Accepts operators, see the Where operators section for details.


include
Used to include related models.


fields
Include or exclude certain fields.


limit
Limit the amount of data returned.


order
Order results by property.


skip
The number of results to skip.


deleted Also return deleted records.
Only available on models that implement soft delete.


Where operators

Where operations work in a similar way as querying a database, there operations can be controled with the following:

# Equal
curl "...?filter[where][type]=invoice"

# And / Or
curl "...?filter[where][<and|or>][0]=condition1&?filter[where][<and|or>]condition2"

# GT / GTE
curl "...?filter[where][date][<gt|get>]=2018-04-01T18:30:00.000Z"

# LT / LTE
curl "...?filter[where][date][<lt|lte>]=2018-04-01T18:30:00.000Z"

# Between
curl "...?filter[where][date][between][0]=2018-04-01T18:30:00.000Z&filter[where][date][between][1]=2018-04-01T18:30:00.000Z"

# INQ / NIN
curl "...?filter[where][type][<inq|nin>]=invoice&filter[where][type][<inq|nin>]=estimate"

# Near
curl "...?filter[where][coordinates][near]=153.536,-28.1"
# or
curl "...?filter[where][coordinates][near]=153.536,-28.1&filter[where][coordinates][maxDistance]=5&filter[where][coordinates][unit]=meters"

# NEQ
curl "...?filter[where][draft][neq]=false"

# LIKE / NLIKE / Options
curl "...?filter[where][number][like]=2018.*"
# or
curl "...?filter[where][number][like]=2018.*&filter[where][number][options]=i"

# Regexp
curl "...?filter[where][number][regexp]=^2018"
// Equal
var queryParams = {
  filter: {
    where: {
      type: 'invoice'
    }
  }
}

// And | Or - Instead of and you can also use or
var queryParams = {
  filter: {
    where: {
      and: [{
          type: 'invoice'
        }, {
          draft: false
        }
      ]
    }
  }
}
// GT / GTE
var queryParams = {
  filter: {
    where: {
      date: {
        gt: '2018-04-01T18:30:00.000Z'
      }
    }
  }
}

// LT / LTE
var queryParams = {
  filter: {
    where: {
      date: {
        lt: '2018-04-01T18:30:00.000Z'
      }
    }
  }
}
// Between
var queryParams = {
  filter: {
    where: {
      date: {
        between: [
          '2017-04-01T18:30:00.000Z',
          '2018-04-01T18:30:00.000Z'
        ]
      }
    }
  }
}
// inq / nin
var queryParams = {
  filter: {
    where: {
      type: {
        inq: [
          "invoice",
          "estimate"
        ]
      }
    }
  }
}
// Near
var queryParams = {
  filter: {
    where: {
      coordinates: {
        near: '153.536,-28.1'
      }
    }
  }
}
//or
var queryParams = {
  filter: {
    where: {
      coordinates: {
        near: '153.536,-28.1',
        maxDistance: 5,
        units: 'meters'
      }
    }
  }
}
// NEQ
var queryParams = {
  filter: {
    where: {
      draft: {
        neq: false
      }
    }
  }
}
// LIKE | NLIKE / options
var queryParams = {
  filter: {
    where: {
      number: {
        like: '2018.*'
      }
    }
  }
}
// or
var queryParams = {
  filter: {
    where: {
      number: {
        like: '2018.*'
        options: i
      }
    }
  }
}
// regExp
var queryParams = {
  filter: {
    where: {
      number: {
        regexp: '2018.*'
      }
    }
  }
}
<?php
  // Equal
  $queryParams = array(
    "filter" => array(
      "where" => array(
        "type" => "invoice"
      )
    )
  );

  // And | Or - Instead of and you can also use or
  $queryParams = array(
    "filter" => array(
      "where" => array(
        "and" => [
          array(
            "type" => "invoice"
          ),
          array(
            "draft" => false
          )
        ]
      )
    )
  );

  // GT / GTE
  $queryParams = array(
    "filter" => array(
      "where" => array(
        "date" => array(
          "gt" => "2018-04-01T18:30:00.000Z"
        )
      )
    )
  );

  // LT / LTE
  $queryParams = array(
    "filter" => array(
      "where" => array(
        "date" => array(
          "lt" => "2018-04-01T18:30:00.000Z"
        )
      )
    )
  );

  // Between
  $queryParams = array(
    "filter" => array(
      "where" => array(
        "date" => array(
          "between" => [
            "2017-04-01T18:30:00.000Z",
            "2018-04-01T18:30:00.000Z"
          ]
        )
      )
    )
  );

  // inq / nin
  $queryParams = array(
    "filter" => array(
      "where" => array(
        "type" => array(
          "inq" => [
            "invoice",
            "estimate"
          ]
        )
      )
    )
  );

  // Near
  $queryParams = array(
    "filter" => array(
      "where" => array(
        "coordinates" => array(
          "near" => "153.536,-28.1"
        )
      )
    )
  );

  //or
  $queryParams = array(
    "filter" => array(
      "where" => array(
        "coordinates" => array(
          "near" => "153.536,-28.1",
          "maxDistance" => 5,
          "units" => "meters"
        )
      )
    )
  );

  // NEQ
  $queryParams = array(
    "filter" => array(
      "where" => array(
        "draft" => array(
          "neq" => false
        )
      )
    )
  );

  // LIKE | NLIKE / options
  $queryParams = array(
    "filter" => array(
      "where" => array(
        "number" => array(
          "like" => "2018.*"
        )
      )
    )
  );

  // or
  $queryParams = array(
    "filter" => array(
      "where" => array(
        "number" => array(
          "like" => "2018.*",
          "options" => "i"
        )
      )
    )
  );

  // regExp
  $queryParams = array(
    "filter" => array(
      "where" => array(
        "number" => array(
          "regexp" => "2018.*"
        )
      )
    )
  );
?>

=
Equivalence.


and
Logical AND operator.


or
Logical OR operator.


gt, gte
Numerical greather than (>); greater than of equal (>=).
Valid for the numberical and the date values.
For Geopoint values, the units are in miles by default.


lt, lte
Numerical less than (<); less than or equal (<=).
Valid only for the numerical and the date values.
For Geopoint values, the units are in miles by default.


between
True if the value is between the two specified values: greater than or equal to the first value, and less than or equal to the second value.


inq, nin
In / not in an array of values.


near
For geolocations, return the closest points, sorted in order of distance.
Use with limit to return the n closest points. maxDistance and unit can also be passed on same level as near to configure the search.


neq
Not equal (!=).


like, nlike, options: i
LIKE / NOT LIKE operators for use with regular expressions with the case insensitive flag.


regexp
Regular expression.


Model custom data

Example custom data

{
  ...
  "custom": {
    "string": "String",
    "boolean": true,
    "object": {},
    "number": 42
  }
}

Most models support adding free form custom data, this is achievable through the custom property which is of type object.

Custom property and it's nested data can also be filtered when querying a model endpoint, see filters section for details.

Soft delete

Soft deleted model object:

{
  "_isDeleted": true,
  "deletedId": "5a3683ea12d5a67dd0ef2f4c",
  "deletedAt": "2020-04-17 16:40:43.714Z"
}

Indicated models are non-permanently (soft) deleted when performing a delete operation on them.

Soft deleted model instances do not appear in any queries. To retrieve soft deleted instances a deleted property must be added to the filter parameter when querying data, see the filters section for more details.

The deleted property can't be used in the count request.

Smart codes

Smart codes are a mechanism that allows placing codes in some text fields that later get replaced by actual values.
For instance we can place the following text inside a Document's note field:
When paying please use reference [document number]
The [document number] notation will get replaced when creating the Document PDF.

Why does this work better than just using the actual document number?
Imagine creating a copy of the mentioned document by copying its values, this would leave us with a note that contains the invalid document number reference. If we instead use the smart code annotation we don't have to worry about the correct number being populated on each document.

Primarily smart codes are used in document properties note, signature and footer.

Types of smart codes:

Your organization

[organization name]


[IBAN]
Bank account number


[SWIFT]
SWIFT / BIC code of bank


[bank]
Name of bank


[address]


[address2]


[zip]
Zip / postal code


[city]


[country]


[tax number]


[company number]


Document

[document number] Current document number.


Calculations

This section is dedicated to understanding the approach we take when calculating totals on documents.

This section comes in handy when setting up front-end calculations to achieve matching values as on the final created documents.

1. Cut-off

In the first stage, we cut any numbers exceeding the one set on the document itself in the decimalPlaces property, default is 4. No rounding is done.

This goes for values like price, priceGross, quantity and discount (if amount).

Any percent or tax values are always cut to 2 decimal places. This includes properties like discount (if percent) and taxRate.

2. Rounding

After each mathematical operation, we round the result to 2 digits, for example after calculating quantity times price we round using half-up rounding strategy and then use the rounded result in the next operation.

Rate limits

The API has a hard limit of 100 requests/second. Exceeding the limit will throw a 429 status.

The Documents create endpoint has a throttler setup after the limiter to ensure consecutive document numbering. In case of a burst the refresh rate of the limiter is set to 10ms meaning that 100 concurrent calls would resolve in 1000ms minimum not including the processing time for each.

Core resources

Accounts

Endpoints:

 POST /v1/accounts
 POST /v1/accounts/login
 POST /v1/accounts/impersonate
  GET /v1/accounts/:id
  GET /v1/accounts/authorized
PATCH /v1/accounts/:id
 POST /v1/accounts/reset
 POST /v1/accounts/reset-password
 POST /v1/accounts/change-password
  GET /v1/accounts/is-unique
  GET /v1/accounts/:id/send-verification
 POST /v1/accountorganizations/accept
 POST /v1/accountorganizations/reject

Accounts represent users that can log in and access different organizations based on the permissions allocated to them.

Space Invoices (root) Account can create new users as child Accounts, a root Account has privileges over those accounts and can manage their access for individual Organizations.

Child accounts can be logged in and controlled by the root account using the impersonate feature.

The Account object

The Account object:

{
  "id": "5e9ab369ed6377000d23d5b5",
  "email": "rocketman@example.com",
  "password": undefined,
  "firstname": "",
  "lastname": "",
  "label": "",
  "taxNumber": "",
  "emailVerified": true,
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z",
  "custom": {}
}

Properties

id string readonly
Unique identifier.


email string


password string writeonly


firstname string
User's first name.


lastname string
User's last name.


label string
User's label.
required if fiscally verifying documents.


taxNumber string
User's personal tax number.
required if fiscally verifying documents.


custom object
Custom data.
See Model custom data section for details.


emailVerified boolean readonly
Indicates if email was verified.


createdAt date readonly
When the instance was created.


updatedAt date readonly
When the instance was last updated.


Create an Account

curl "https://api.spaceinvoices.com/v1/accounts" \
  -H "Authorization: LAUNCH_CODE" \
  -d email="rocketman@example.com" \
  -d password="supersecret"
spaceInvoices.accounts
  .create({
    email: "rocketman@example.com",
    password: "supersecret",
  })
  .then(function (account) {
    // Use the Account
  });
<?php
  Spaceinvoices\Accounts::create(array(
    "email" => "rocketman@example.com",
    "password" => "supersecret"
  ));
?>

Returns:

{
  "id": "5e9ab369ed6377000d23d5b5",
  "email": "rocketman@example.com",
  "firstname": "",
  "lastname": "",
  "label": "",
  "taxNumber": "",
  "emailVerified": true,
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z",
  "custom": {}
}

HTTP Request

POST https://api.spaceinvoices.com/v1/accounts

Properties

email string required


password string required


firstname string
User's first name.


lastname string
User's last name.


label string
User's label.
required if fiscally verifying documents.


taxNumber string
User's personal tax number.
required if fiscally verifying documents.


custom object
Custom data.
See Model custom data section for details.


Log in an Account

curl "https://api.spaceinvoices.com/v1/accounts/login" \
  -d email="rocketman@example.com" \
  -d password="supersecret"
spaceInvoices.accounts
  .login({
    email: "rocketman@example.com",
    password: "supersecret",
  })
  .then(function (token) {
    // Use the Access Token
  });
<?php
  Spaceinvoices\Accounts::login(array(
    "email" => "rocketman@example.com",
    "password" => "supersecret"
  ));
?>

Returns:

{
  "id": "5e9ab369ed6377000d23d5b5",
  "email": "rocketman@example.com",
  "firstname": "",
  "lastname": "",
  "label": "",
  "taxNumber": "",
  "emailVerified": true,
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z",
  "custom": {}
}

This endpoint authenticates an Account and returns an Access Token object which includes the launch code that can be used to make authenticated calls to the API.

HTTP Request

POST https://api.spaceinvoices.com/v1/accounts/login

Properties

email string required


password string required


ttl number default 2 months
Time to live.
Determines when the token will expire from time of creation.
To create a non-expiring token use ttl=-1


HTTP Response

Returns an Access Token object.

Properties

id string readonly
Unique identifier.


email string


password string writeonly


firstname string
User's first name.


lastname string
User's last name.


label string
User's label.
required if fiscally verifying documents.


taxNumber string
User's personal tax number.
required if fiscally verifying documents.


custom object
Custom data.
See Model custom data section for details.


emailVerified boolean readonly
Indicates if email was verified.


createdAt date readonly
When the instance was created.


updatedAt date readonly
When the instance was last updated.


Impersonate an Account

curl "https://api.spaceinvoices.com/v1/accounts/impersonate" \
  -H "Authorization: LAUNCH_CODE" \
  -d email="rocketman@example.com"

Returns:

{
  "id": "5e9ab369ed6377000d23d5b5",
  "email": "rocketman@example.com",
  "firstname": "",
  "lastname": "",
  "label": "",
  "taxNumber": "",
  "emailVerified": true,
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z",
  "custom": {}
}

A root Space Invoices Account can retrieve a launch code for any of their child Accounts using either the child Account's id or email. This functionality is useful for logging in related users without the need of knowing or asking for their login credentials.

Important consideration: Any Account created through the API by a root Account is considered a child of the creator. If a child Account creates another Account, that Account is considered a child of the root Account.

Requires the root Account's launch code in headers or query parameters.

HTTP Request

POST https://api.spaceinvoices.com/v1/accounts/impersonate

Properties

email string
Email of Account to impersonate.
Required if id not provided.


id string
ID of Account to impersonate.
Required if email not provided.


ttl number default 2 months
Time to live.
Determines when the token will expire from time of creation.
To create a non-expiring token use ttl=-1


HTTP Response

Returns an Access Token object for the Account being impersonated.

Properties

id string readonly
Unique identifier.


email string


password string writeonly


firstname string
User's first name.


lastname string
User's last name.


label string
User's label.
required if fiscally verifying documents.


taxNumber string
User's personal tax number.
required if fiscally verifying documents.


custom object
Custom data.
See Model custom data section for details.


emailVerified boolean readonly
Indicates if email was verified.


createdAt date readonly
When the instance was created.


updatedAt date readonly
When the instance was last updated.


Retrieve an Account

curl "https://api.spaceinvoices.com/v1/accounts/5e9ab369ed6377000d23d5b5" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "id": "5e9ab369ed6377000d23d5b5",
  "email": "rocketman@example.com",
  "firstname": "",
  "lastname": "",
  "label": "",
  "taxNumber": "",
  "emailVerified": true,
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z",
  "custom": {}
}

HTTP Request

GET https://api.spaceinvoices.com/v1/accounts/:id

Route parameters

id string required
ID of the Account being retrieved


Verifying if Account is authorized

curl "https://api.spaceinvoices.com/v1/accounts/authorized" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "id": "5e9ab369ed6377000d23d5b5",
  "email": "rocketman@example.com",
  "firstname": "",
  "lastname": "",
  "label": "",
  "taxNumber": "",
  "emailVerified": true,
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z",
  "custom": {}
}

Convenience endpoint for verifying a launch code validity or retrieving an Account based on the provided launch code without knowing the Account's ID.

Returns 401 or the authenticated Account's data.

HTTP request

GET https://api.spaceinvoices.com/v1/accounts/authorized

Requesting a password reset token

curl "https://api.spaceinvoices.com/v1/accounts/reset" \
  -d email="rocketman@example.com"

Returns:

HTTP status 204

The endpoint requests a password reset token which is sent to the email for which the token is requested.

HTTP Request

POST https://api.spaceinvoices.com/v1/accounts/reset

Properties

email string required


Resetting an Account's password

curl "https://api.spaceinvoices.com/v1/accounts/reset-password" \
  -H "Authorization: LAUNCH_CODE"
  -d password="supersecret"

Returns:

HTTP status 204

A password reset token can be used to change an Account's password if forgotten.

The password reset token retrieved from email must be sent in the headers or query parameters of the request.

HTTP Request

POST https://api.spaceinvoices.com/v1/accounts/reset-password

Properties

password string required


Change an Account's password

curl "https://api.spaceinvoices.com/v1/accounts/change-password" \
  -H "Authorization: LAUNCH_CODE" \
  -d oldPassword="supersecret" \
  -d newPassword="ultimatesecret"

Returns:

HTTP status 204

HTTP Request

POST https://api.spaceinvoices.com/v1/accounts/change-password

Properties

oldPassword string required


newPassword string required


Check if an email is unique

curl "https://api.spaceinvoices.com/v1/accounts/is-unique?email=rocketman@example.com"
spaceInvoices.accounts
  .isUnique("rocketman@example.com")
  .then(function (response) {
    // Use the response
  });
<?php
  Spaceinvoices\Accounts::isUnique("rocketman@example.com");
?>

Returns:

{
  "isUnique": true
}

This endpoint returns a boolean value if the email exists in the system already or not.

Please note: Special characters should be URL encoded, otherwise they will be stripped which may cause inaccurate results!

HTTP Request

GET https://api.spaceinvoices.com/v1/accounts/is-unique?email=:email

Route parameters

email string required
Email to verify.


HTTP Response

Properties

isUnique boolean
If the email is unique.


Accepting an invitation

curl "https://api.spaceinvoices.com/v1/accountorganizations/5e9ab369ed6377000d23d5b5/accept" \
  -H "Authorization: LAUNCH_CODE"

HTTP Request

GET https://api.spaceinvoices.com/v1/accountorganizations/:id/accept

Route parameters

id string required
ID of the Access being accepted


Returns:

{
  "success": true
}

This endpoint allows accepting an open invitation for access to an Organization.

See Organization for more details.

Rejecting an invitation

curl "https://api.spaceinvoices.com/v1/accountorganizations/5e9ab369ed6377000d23d5b5/reject" \
  -H "Authorization: LAUNCH_CODE"

HTTP Request

GET https://api.spaceinvoices.com/v1/accountorganizations/:id/reject

Route parameters

id string required
ID of the Access being rejected


Returns:

Returns:

{
  "success": true
}

This endpoint allows rejecting an open invitation for access to an Organization.

See Organization for more details.

Clients

Endpoints:

  POST /v1/organizations/:id/clients
   GET /v1/clients/:id
 PATCH /v1/clients/:id
DELETE /v1/clients/:id
   GET /v1/organizations/:id/clients
   GET /v1/organizations/:id/clients/count
   GET /v1/organizations/:id/search-clients

Clients are businesses, end users, organizations, and any other entity that can receive a document from an organization. Clients may be saved and later referenced using their unique ID or email.

The Client object

The Client object:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "organizationId": "5a3683ea12d5a67dd0ef2f4d",
  "name": "Space Exploration Technologies corp",
  "address": "Rocket Road",
  "city": "Hawthorne",
  "zip": "CA 90250",
  "country": "USA",
  "email": "elon@spaceinvoices.com",
  "contact": "Elon M.",
  "phone": "+1 123 456 7890",
  "isEndCustomer": false,
  "companyNumber": null,
  "IBAN": null,
  "bank": null,
  "SWIFT": null,
  "website": null,
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z"
}

Properties

id string readonly
Unique identifier.


organizationId string readonly
ID reference to Organization the Client belongs to.


name string
Required only if clientId not provided on Document.


address string
Address.


address2 string
Address additional.


city string
City.


zip string
Zip/postal code.


state string
State or region.


country string
Country.


taxNumber string
Organization VAT / GST / sales tax or similar tax number.


taxSubject boolean
Indicates if the Client is subject to tax.


companyNumber string
Organization registration or similar number.


IBAN string
Bank account number.


bank string
Bank name.


SWIFT string
Bank SWIFT/BIC.


website string
Website address.


email string
Contact email.
If provided and clientId not provided will be used to find matching Client to populate clientId.


phone string
Contact phone.


isEndCustomer boolean
Indicates if Client is end customer ie. person.


custom object
Custom data.
See Model custom data section for details.


createdAt date readonly
When the instance was created.


updatedAt date readonly
When the instance was last updated.


Create a Client

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/clients" \
  -H "Authorization: LAUNCH_CODE" \
  -d name="Space Exploration Technologies corp" \
  -d address="Rocket Road" \
  -d city="Hawthorne" \
  -d zip="CA 90250" \
  -d country="USA" \
  -d email="info@spacex.com" \
  -d contact="Elon M." \
  -d phone="+1 123 456 7890"
spaceInvoices.clients
  .create("ORG_ID", {
    name: "Space Exploration Technologies corp",
    address: "Rocket Road",
    city: "Hawthorne",
    zip: "CA 90250",
    country: "USA",
    email: "info@spacex.com",
    contact: "Elon M.",
    phone: "+1 123 456 7890",
  })
  .then(function (client) {
    // Use the client
  });
<?php
  Spaceinvoices\Clients::create("ORG_ID", array(
    "name" => "Space Exploration Technologies corp",
    "address" => "Rocket Road",
    "city" => "Hawthorne",
    "zip" => "CA 90250",
    "country" => "USA",
    "email" => "info@spacex.com",
    "contact" => "Elon M.",
    "phone" => "+1 123 456 78900"
  ));
?>

Returns:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "organizationId": "5a3683ea12d5a67dd0ef2f4d",
  "name": "Space Exploration Technologies corp",
  "address": "Rocket Road",
  "city": "Hawthorne",
  "zip": "CA 90250",
  "country": "USA",
  "email": "elon@spaceinvoices.com",
  "contact": "Elon M.",
  "phone": "+1 123 456 7890",
  "isEndCustomer": false,
  "companyNumber": null,
  "IBAN": null,
  "bank": null,
  "SWIFT": null,
  "website": null,
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z"
}

HTTP Request

POST https://api.spaceinvoices.com/v1/organizations/:id/clients

Route parameters

id string required
ID of the Organization on which the Client is being created


Properties

name string required
Required only if clientId not provided on Document.


address string
Address.


address2 string
Address additional.


city string
City.


zip string
Zip/postal code.


state string
State or region.


country string
Country.


taxNumber string
Organization VAT / GST / sales tax or similar tax number.


taxSubject boolean
Indicates if the Client is subject to tax.


companyNumber string
Organization registration or similar number.


IBAN string
Bank account number.


bank string
Bank name.


SWIFT string
Bank SWIFT/BIC.


website string
Website address.


email string
Contact email.
If provided and clientId not provided will be used to find matching Client to populate clientId.


phone string
Contact phone.


isEndCustomer boolean default false
Indicates if Client is end customer ie. person.


custom object
Custom data.
See Model custom data section for details.


Retrieve a Client

curl "https://api.spaceinvoices.com/v1/clients/5a3683ea12d5a67dd0ef2f4c" \
  -H "Authorization: LAUNCH_CODE"
spaceInvoices.clients.getById(clientId).then(function (client) {
  // Use the client
});
<?php
  Spaceinvoices\Clients::getById("5a3683ea12d5a67dd0ef2f4c");
?>

Returns:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "organizationId": "5a3683ea12d5a67dd0ef2f4d",
  "name": "Space Exploration Technologies corp",
  "address": "Rocket Road",
  "city": "Hawthorne",
  "zip": "CA 90250",
  "country": "USA",
  "email": "elon@spaceinvoices.com",
  "contact": "Elon M.",
  "phone": "+1 123 456 7890",
  "isEndCustomer": false,
  "companyNumber": null,
  "IBAN": null,
  "bank": null,
  "SWIFT": null,
  "website": null,
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z"
}

HTTP Request

GET https://api.spaceinvoices.com/v1/clients/:id

Route parameters

id string required
ID of the Client being retrieved


Update a Client

curl -X PATCH "https://api.spaceinvoices.com/v1/clients/5a3683ea12d5a67dd0ef2f4c" \
  -H "Authorization: LAUNCH_CODE" \
  -d name="Space Exploration Technologies corp"
spaceInvoices.clients
  .edit("5a3683ea12d5a67dd0ef2f4c", {
    name: "Space Exploration Technologies corp",
    address: "Rocket Road",
    city: "Hawthorne",
    zip: "CA 90250",
    country: "USA",
    email: "info@spacex.com",
    contact: "Elon M.",
    phone: "+1 123 456 7890",
  })
  .then(function (client) {
    // Use the client
  });
<?php
  Spaceinvoices\Clients::edit("5a3683ea12d5a67dd0ef2f4c", array(
    "name" => "Space Exploration Technologies corp",
    "address" => "Rocket Road",
    "city" => "Hawthorne",
    "zip" => "CA 90250",
    "country" => "USA",
    "email" => "info@spacex.com",
    "contact" => "Elon M.",
    "phone" => "+1 123 456 78900"
  ));
?>

Returns:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "organizationId": "5a3683ea12d5a67dd0ef2f4d",
  "name": "Space Exploration Technologies corp",
  "address": "Rocket Road",
  "city": "Hawthorne",
  "zip": "CA 90250",
  "country": "USA",
  "email": "elon@spaceinvoices.com",
  "contact": "Elon M.",
  "phone": "+1 123 456 7890",
  "isEndCustomer": false,
  "companyNumber": null,
  "IBAN": null,
  "bank": null,
  "SWIFT": null,
  "website": null,
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z"
}

HTTP Request

PATCH https://api.spaceinvoices.com/v1/clients/:id

Route parameters

id string required
ID of the Client being updated


Properties

name string
Required only if clientId not provided on Document.


address string
Address.


address2 string
Address additional.


city string
City.


zip string
Zip/postal code.


state string
State or region.


country string
Country.


taxNumber string
Organization VAT / GST / sales tax or similar tax number.


taxSubject boolean
Indicates if the Client is subject to tax.


companyNumber string
Organization registration or similar number.


IBAN string
Bank account number.


bank string
Bank name.


SWIFT string
Bank SWIFT/BIC.


website string
Website address.


email string
Contact email.
If provided and clientId not provided will be used to find matching Client to populate clientId.


phone string
Contact phone.


isEndCustomer boolean
Indicates if Client is end customer ie. person.


custom object
Custom data.
See Model custom data section for details.


Delete a Client

curl -X DELETE "https://api.spaceinvoices.com/v1/clients/5a3683ea12d5a67dd0ef2f4c" \
  -H "Authorization: LAUNCH_CODE"
spaceInvoices.clients.delete("5a3683ea12d5a67dd0ef2f4c").then(function (count) {
  // Deleted count
});
<?php
  Spaceinvoices\Clients::delete("5a3683ea12d5a67dd0ef2f4c");
?>

Returns:

{
  "count": 1
}

HTTP Request

DELETE https://api.spaceinvoices.com/v1/clients/:id

Route parameters

id string required
ID of the Client being deleted


List all Clients

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/clients" \
  -H "Authorization: LAUNCH_CODE"
spaceInvoices.clients.list("ORG_ID").then(function (clients) {
  // Use the clients
});
<?php
  Spaceinvoices\Clients::find("ORG_ID");
?>

Returns:

[{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "organizationId": "5a3683ea12d5a67dd0ef2f4d",
  "name": "Space Exploration Technologies corp",
  "address": "Rocket Road",
  "city": "Hawthorne",
  "zip": "CA 90250",
  "country": "USA",
  "email": "elon@spaceinvoices.com",
  "contact": "Elon M.",
  "phone": "+1 123 456 7890",
  "isEndCustomer": false,
  "companyNumber": null,
  "IBAN": null,
  "bank": null,
  "SWIFT": null,
  "website": null,
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z"
}, ...]

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/clients

Route parameters

id string required
ID of the Organization on which the clients are being listed


filter object
Query filters. See Filters section for more details.


Count all Clients

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/clients/count" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "count": 1
}

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/clients/count

Route parameters

id string required
ID of the Organization on which the clients are being counted


where object
Query where. See Where operators section of filters for more details.


Search all Clients

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/clients/search?term=Space" \
  -H "Authorization: LAUNCH_CODE"
spaceInvoices.clients.search("ORG_ID", "space").then(function (clients) {
  // Use the clients
});
<?php
  Spaceinvoices\Clients::search("ORG_ID", "space");
?>

Returns:

[{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "organizationId": "5a3683ea12d5a67dd0ef2f4d",
  "name": "Space Exploration Technologies corp",
  "address": "Rocket Road",
  "city": "Hawthorne",
  "zip": "CA 90250",
  "country": "USA",
  "email": "elon@spaceinvoices.com",
  "contact": "Elon M.",
  "phone": "+1 123 456 7890",
  "isEndCustomer": false,
  "companyNumber": null,
  "IBAN": null,
  "bank": null,
  "SWIFT": null,
  "website": null,
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z"
}, ...]

Convenience method for searching client by multiple fields.

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/clients/search?term=:term

Route parameters

id string required
ID of the Organization on which te clients are being searched


term string required
Term to search for.


Defaults

Endpoints:

  POST /v1/organizations/:id/defaults
   GET /v1/defaults/:id
 PATCH /v1/defaults/:id
DELETE /v1/defaults/:id
   GET /v1/organizations/:id/defaults
   GET /v1/organizations/:id/defaults/count

Defaults serve as system-defined and user-defined settings for an Organization.
Besides the predefined system values, any additional value can be added to this model as custom settings.

The defaults are included with the organization model when it is retrieved for ease of use.

The Default object

The Default object:

{
  "id": "5e9ab369ed6377000d23d5b5",
  "name": "currencyId",
  "value": "EUR",
  "organizationId": "5e9e92107f186e000eda09cf",
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z"
}

Properties

id string readonly
Unique identifier.


organizationId string readonly
ID reference to Organization the Default belongs to.


name string
Unique name of Default.
Must be unique for each Default in Organization.
Can't be updated.


value any
Value of Default, can be any data type.


createdAt date readonly
When the instance was created.


updatedAt date readonly
When the instance was last updated.


Create a Default

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/defaults" \
  -H "Authorization: LAUNCH_CODE" \
  -d name="currencyId" \
  -d value="EUR"

Returns:

{
  "id": "5e9ab369ed6377000d23d5b5",
  "name": "currencyId",
  "value": "EUR",
  "organizationId": "5e9e92107f186e000eda09cf",
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z"
}

HTTP Request

POST https://api.spaceinvoices.com/v1/organizations/:id/defaults

Route parameters

id string required
ID of the Organization on which the Default is being created


Properties

name string required
Unique name of Default.
Must be unique for each Default in Organization.
Can't be updated.


value any required
Value of Default, can be any data type.


Retrieve a Default

curl "https://api.spaceinvoices.com/v1/defaults/5e9ab369ed6377000d23d5b5" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "id": "5e9ab369ed6377000d23d5b5",
  "name": "currencyId",
  "value": "EUR",
  "organizationId": "5e9e92107f186e000eda09cf",
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z"
}

HTTP Request

GET https://api.spaceinvoices.com/v1/defaults/:id

Route parameters

id string required
ID of the Default being retrieved


Update a Default

curl "https://api.spaceinvoices.com/v1/defaults/5e9ab369ed6377000d23d5b5" \
  -H "Authorization: LAUNCH_CODE" \
  -d value="EUR"

Returns:

{
  "id": "5e9ab369ed6377000d23d5b5",
  "name": "currencyId",
  "value": "EUR",
  "organizationId": "5e9e92107f186e000eda09cf",
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z"
}

HTTP Request

PATCH https://api.spaceinvoices.com/v1/defaults/:id

Route parameters

id string required
ID of the Default being updated


Properties

name string
Unique name of Default.
Must be unique for each Default in Organization.
Can't be updated.


value any
Value of Default, can be any data type.


Delete a Default

curl -X DELETE "https://api.spaceinvoices.com/v1/defaults/5e9ab369ed6377000d23d5b5" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "count": 1
}

HTTP Request

DELETE https://api.spaceinvoices.com/v1/defaults/:id

Route parameters

id string required
ID of the Default being deleted


List all Defaults

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/defaults" \
  -H "Authorization: LAUNCH_CODE"

Returns:

[{
  "id": "5e9ab369ed6377000d23d5b5",
  "name": "currencyId",
  "value": "EUR",
  "organizationId": "5e9e92107f186e000eda09cf",
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z"
}, ...]

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/defaults

Route parameters

id string required
ID of the Organization on which the defaults are being listed


filter object
Query filters. See Filters section for more details.


Count all Defaults

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/defaults/count" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "count": 1
}

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/defaults/count

Route parameters

id string required
ID of the Organization on which the defaults are being counted


where object
Query where. See Where operators section of filters for more details.


Documents

Endpoints:

  POST /v1/organizations/:id/documents
   GET /v1/documents/:id
   PUT /v1/documents/:id
DELETE /v1/documents/:id
   GET /v1/organizations/:id/documents
   GET /v1/organizations/:id/documents/count
   GET /v1/documents/:id/pdf
  POST /v1/documents/:id/send
  POST /v1/documents/:id/cancel
  POST /v1/documents/:id/uncancel
  POST /v1/documents/:id/mark-sent

Documents, the core of our service, are the most complex part of Space Invoices.

For this reason, we have taken a lot of care to provide you with a wide array of options when creating different documents. Most importantly, we allow you to provide as much or as little data as you wish as the API takes care of the rest. The API can automate based on known data such as the organization settings, country of origin, and the country of destination.

NOTE: We have improved how taxes can be loaded to document items. Normally, a tax can be added to document items by adding taxId property to the _documentItems[]._documentItemTaxes array, but the responsibility of knowing tax ids is placed on the user.
To simplify, we now have a feature that allows referencing a tax by its rate or classification instead of just the normal id. The API will then smartly load the best match from the taxes paid for by the organization.

The Document object

The Document object:

{
  "id": "5e9ab369ed6377000d23d5b5",
  "number": "2020-00001",
  "type": "invoice",
  "date": "2020-04-18T07:59:37.902Z",
  "dateDue": "2020-05-18T00:00:00.000Z",
  "dateService": "2020-04-18T07:59:37.902Z",
  "dateServiceTo": "2020-04-18T07:59:37.902Z",
  "dateValidTill": "2020-05-18T00:00:00.000Z",
  "datePaid": "2020-04-18T07:59:37.902Z",
  "reference": "",
  "draft": false,
  "currencyId": "EUR",
  "canceled": false,
  "clientId": "5e9ab369ed6377000d23d5b4",
  "accountId": "5e9ab369ed6377000d23d599",
  "organizationId": "5e9ab369ed6377000d23d59b",
  "_documentClient": {
    "id": "422d1fd5-d8e6-4635-8b16-107679a364f8",
    "name": "Rocket man",
    "country": "United Kingdom",
    "address": undefined,
    "address2": undefined,
    "city": undefined,
    "zip": undefined,
    "state": undefined,
    "taxNumber": undefined,
    "taxSubject": false,
    "companyNumber": undefined,
    "IBAN": undefined,
    "bank": undefined,
    "SWIFT": undefined,
    "website": undefined,
    "email": undefined,
    "phone": undefined,
    "isEndCustomer": false,
    "custom": {}
  },
  "_documentIssuer": {
    "id": "66953056-3253-41e8-9657-59bd9c254dda",
    "name": "International Space Agency",
    "address": "Rocket street 1",
    "address2": "",
    "city": "Brussels",
    "zip": "10000",
    "state": "",
    "country": "Belgium",
    "countryAlpha2Code": "BE",
    "taxNumber": "10489185",
    "taxSubject": true,
    "companyNumber": "0987654321",
    "IBAN": "GB49 REVO 0099 6979 5754 56",
    "bank": "Revolut ltd",
    "SWIFT": "",
    "website": "https://spaceinvoices.com",
    "email": "info@spaceinvoices.com",
    "phone": "+32 466 903 942",
    "custom": {}
  },
  "_documentItems": [
    {
      "id": "8946edb4-946e-4aed-bebd-299b74c3b663",
      "itemId": "5e9a22366d3a80000e8797b0",
      "name": "Space suit",
      "description": "",
      "price": 1000,
      "priceGross": undefined,
      "quantity": 2,
      "discount": 0,
      "discountIsAmount": false,
      "unit": "Item",
      "SKU": undefined,
      "isSeparator": false,
      "total": 2000,
      "totalWithTax": 2420,
      "totalDiscount": 0,
      "totalTax": 420,
      "_documentItemTaxes": [
        {
          "id": "508cae6c-2b28-4607-8a95-9a3066d6077f",
          "taxId": "5e9ac7df1ccbec000de73263",
          "name": "Belasting over de toegevoegde waarde",
          "abbreviation": "BTW",
          "rate": 21,
          "recoverable": true
          "reverseCharged": false,
          "compound": false,
        }
      ],
      "custom": {},
    }
  ],
  "note": "Please pay to bank account GB49 REVO 0099 6979 5754 56.\nWhen paying please use reference 2020-00001.\n\nThank you for your business",
  "signature": "International Space Agency",
  "footer": "International Space Agency, Rocket street 1, 10000 Brussels, Belgium, tax num.: 10489185, company num.: 0987654321",
  "documentIds": [],
  "uniqueId": undefined,
  "decimalPlaces": 4,
  "total": 2000,
  "totalConverted": undefined,
  "totalWithTax": 2420,
  "totalWithTaxConverted": undefined,
  "totalDiscount": 0,
  "totalPaid": 0,
  "totalDue": 2420,
  "paidInFull": false,
  "hasUnit": true,
  "sentSnailMail": false,
  "_documentTaxes": [
    {
      "tax": 21,
      "taxId": "5e9ac7df1ccbec000de73263",
      "base": 2000,
      "totalTax": 420
    }
  ],
  "_documentReverseTaxes": [],
  "_documentConversionRate": [],
  "validateEslog": undefined,
  "isValidEslog": false,
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z"
}

Properties

id string readonly
Unique identifier.


organizationId string readonly
ID reference to Organization the Document belongs to.


accountId string readonly
ID reference to Account that created the Document.


number string
Document number.
Must be unique for each Document type in Organization.


type string
Type of document, one of invoice, estimate, advance, credit-note, delivery-note.
Certain Document property rules behave differently depending on document type.
Can't be updated.


date date
Date Document was created/issued.


dateDue date
Date invoice is due.
Auto populated using Organization's default due days invoice_dueDays from today.
Only present if type=invoice.


dateService date
Date the service was started or conducted.
Only present if type=invoice.


dateServiceTo date
The date the service ends if multi-day service.
Only present if type=invoice.


dateValidTill date
Date the estimate is valid until.
Auto populated using Organization's default days valid until estimate_validTillDays from today.
Only present if type=estimate.


datePaid date
Date the advance was paid on.
Only present if type=advance.


reference string
Reference number of document Unique per Document type on Organization. Can be used for payment reference where Document number not in the appropriate format.


draft boolean
If the document is a draft.
If set to false the property cannot go back to true.
Only settable if type=invoice.


currencyId string
ISO 4217 currency code. Wikipedia
If not provided, the Organization's default currency is used.


canceled boolean readonly
Indicates if document is canceled/voided.
See Cancel document section on how to cancel a Document.


clientId string
ID reference to the Organization's Client.
If provided _documentClient object gets populated using referenced Client.


_documentClient object
Document Client data.
Property is optional if clientId is provided.
If populated based on clientId reference any key defined in this object will take precedence.
If clientId is not provided and email is set will attempt to match client in the database based on email. If clientId is not provided, the data in the object is saved to the Organization's Clients, clientId is populated with saved Client.

toggle child attributes

id readonly
Unique nested object identifier.


name string
Name of Client.
Optional if clientId provided on Document.


address string
Address.


address2 string
Address additional.


city string
City.


zip string
Zip/postal code.


state string
State or region.


country string
Country.


taxNumber string
Organization VAT / GST / sales tax or similar tax number.


taxSubject boolean
Indicates if the Client is subject to tax.


companyNumber string
Organization registration or similar number.


IBAN string
Bank account number.


bank string
Bank name.


SWIFT string
Bank SWIFT/BIC.


website string
Website address.


email string
Contact email.
If provided and clientId not provided will be used to find matching Client to populate clientId.


phone string
Contact phone.


isEndCustomer boolean
Indicates if Client is end customer ie. person.


custom object
Custom data.
See Model custom data section for details.


_documentIssuer object
Document Issuer data.
Property is automatically populated with Organization data.
Any key that is provided in the object will take precedence, useful for per-document changes.

toggle child attributes

id string readonly
Unique nested object identifier.


name string
Name.


address string


address2 string
Address additional.


city string


zip string
Zip / postal code.


state string
State or region.


country string


countryAlpha2Code string readonly
Country ISO alpha-2 code. Wikipedia. API automatically parses Organization address details to determine the Organization's country and populates property based on the result.


taxNumber string
Organization VAT / GST / sales tax or similar tax number.


taxSubject boolean
Indicates if the Organization is subject to tax.


companyNumber string
Organization registration or similar number.


IBAN string
Bank account number.


bank string
Bank name.


SWIFT string
Bank SWIFT/BIC.


website string
Website address.
Displayed on some PDF templates.


email string
Email.
Displayed on some PDF templates.


phone string
Phone.
Displayed on some PDF templates.


custom object
Custom data.
See Model custom data section for details.



_documentItems array
Collection of Document Items.

toggle child attributes

id string readonly
Unique nested object identifier.


itemId string
ID reference to the Organization's item.
If set and property load=true, the item properties are populated from the referenced item, any key provided here will take precedence.


name string
Name of item.
Optional if isSeparator is set to true or if itemId or SKU is provided and load is true.


description
Description of the item.


price number
Price per single item.


priceGross number
Gross price per single item.
If provided price is calculated from it.


quantity number
Quantity of items.


discount number
Discount percent.
If discountIsAmount=true then it is regarded as a value discount instead of percent.


discountIsAmount boolean
Indicates if discount is value based instead of percent.


unit string
Unit of measurement for the item ie. Item, Service, Meter, etc.


SKU string
SKU of the Item, can reference the Organization's Item by SKU property.
If provided and itemId not provided and property load=true, the item properties are populated from the referenced item, any key that is provided will take precedence.


isSepatator boolean
Indicates if item is separator.
Used for visually separating line items and naming groups of line items.
If true all properties except name and description are dropped.


custom object
Custom data.
See Model custom data section for details.


total number readonly
Calculated item sum without tax.


totalWithTax number readonly
Calculated item sum with tax.


totalDiscount number readonly
Calculated item sum discount.


totalTax number readonly
Calculated item sum tax.


_documentItemTaxes object
Collection of Document Item Taxes.

toggle definition

id string readonly
Unique nested object identifier.


taxId string
ID reference to Organization's Tax.
If the property is provided rate, recoverable and compound properties are auto-populated. Note that the rate is chosen based on the date property of Document if Tax has multiple rates associated with it.


name string
Full name of tax.


abbreviation string
Abbreviation of tax, used for display.


rate number
Tax rate percent.
If provided, the API attempts to match the tax from the database and populate it.


classification string
Tax classification.
If provided and rate not provided, the API attempts to match tax by it from the database and populate it.


recoverable boolean
If the tax is recoverable.


reverseCharged boolean
If the tax is reverse (self) charged.
Reverse charged tax is not applied to totals and is added to the Document's reverse taxes.


compound boolean
If tax is compound.
Compound tax is calculated on top of the total with tax sum after other taxes that are applied to the Item.


save boolean unpersisted
If the item should be saved.
If true the item is saved to the Organization's collection of items. The document item is also populated with the item's ID in the itemId field. NOTE: Ignored if itemId is also provided.


custom object
Custom data.
See Model custom data section for details.


note string
Note for Document.
Populated with the Organization's default if not provided. May contain shortcode notations which get parsed to data on PDF or when parseForDisplay flag is provided.


signature string
Signature for the Document.
Populated with the Organization default if not provided. May contain shortcode notations which get parsed to data on PDF or when parseForDisplay flag is provided.


footer string
Footer for the Document.
Populated with the Organizaion's default if not provided. May contain shortcode notations which get parsed to data on PDF or when parseForDisplay flag is provided.


documentIds array
Collection of IDs of referenced Documents.
Used for stating Document references on PDFs.


uniqueId string
Used to prevent double issuing of the same Document in case of network errors.
Will throw error if Document with same value already exists.


decimalPlaces number
Number of decimal places to which the Document items are trimmed and rounded in calculations.
Should be 4 in most cases.


validateEslog boolean
If the validation for Eslog format should throw an error.


payments array
Collection of related Payments.
Can be included, see Filters section for details. Can be populated on create Document to create Payments as well.


total number readonly
Calculated Document sum without tax.


totalConverted number readonly
The total converted to local currency if the Document in a foreign one.


totalWithTax number readonly
Calculated Document sum with tax.


totalWithTaxConverted string readonly
The totalWithTax converted to local currency if the Document is in a foreign one.


totalDiscount number readonly
Calculated Document sum discount.


totalPaid number readonly
The calculated sum of all added Payments.


totalDue number readonly
The calculated sum of remaining Payments.


paidInFull boolean readonly
If the Document has been paid in full based on added Payments.


hasUnit boolean readonly
If there is at least one Document Item with unit defined.
Used for displaying unit column.


sentSnailMail boolean
If the Document was sent using regular mail.


_documentTaxes array readonly
Collection of Document's unique taxes.

toggle child attributes

tax number
Tax rate percent.


taxId string
ID reference of Tax.


base number
Value base for a given tax calculation.


totalTax number
The total sum of a given tax.


_documentReverseTaxes readonly
Collection Document unique Reverse Taxes.

toggle child attributes

tax number
Tax rate percent.


taxId string
ID reference to Tax.


base number
The value base for a given tax calculation.


totalTax number
The total sum of a given tax.


_documentConversionRate object readonly
Currency conversion rate data.
Property is automatically populated with data if Document currencyId is set to a currency that is not the Organization's default.
Can be manually populated.
Also generates a disclaimer on a generated document PDF.

toggle child attributes


date date
Date of conversion rate data.
Usually the date of document except in cases when the data is not available ie. holidays, then the first available date following.


from string
Currency conversion is made from.


to string
Currency conversion is made into.


rate number
Conversion rate value.


source string
Source of conversion rate data.
ie. European Central Bank.


isValidEslog boolean readonly
If Document has passed Eslog format validation.
Used to determine if output xml file of format is possible.


createdAt date readonly
When the instance was created.


updatedAt date readonly
When the instance was last updated.


Create a Document

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/documents" \
  -H "Authorization: LAUNCH_CODE" \
  -d _documentClient[name]="Rocket Man" \
  -d _documentClient[country]="United Kingdom" \
  -d _documentItems[0][name]="Space suit" \
  -d _documentItems[0][quantity]=2 \
  -d _documentItems[0][unit]="Item" \
  -d _documentItems[0][price]="1000" \
  -d _documentItems[0][_documentItemTaxes][0][rate]=21
spaceInvoices.documents
  .create(organization.id, {
    _documentClient: {
      name: "Rocket Man",
      country: "USA",
    },
    _documentItems: [
      {
        name: "Space suit",
        quantity: 2,
        unit: "Item",
        price: 1000,
        _documentItemTaxes: [
          {
            rate: 21,
          },
        ],
      },
    ],
  })
  .then(function (document) {
    // Use the document
  });
<?php
  Spaceinvoices\Documents::create("ORGANIZATION_ID", array(
    "type" => "estimate",
    "_documentClient" => array(
      "name" => "Rocket Man",
      "country" => "United Kingdom"
    ),
    "_documentItems" => [
      array(
        "name" => "Space suit",
        "quantity" => 2,
        "unit" => "Item",
        "price" => 1000,
        "_documentItemTaxes" => [
          array(
            "rate": 21
          )
        ]
      )
    ]
  ));
?>

Returns:

{
  "id": "5e9ab369ed6377000d23d5b5",
  "number": "2020-00001",
  "type": "invoice",
  "date": "2020-04-18T07:59:37.902Z",
  "dateDue": "2020-05-18T00:00:00.000Z",
  "dateService": "2020-04-18T07:59:37.902Z",
  "dateServiceTo": "2020-04-18T07:59:37.902Z",
  "dateValidTill": "2020-05-18T00:00:00.000Z",
  "datePaid": "2020-04-18T07:59:37.902Z",
  "reference": "",
  "draft": false,
  "currencyId": "EUR",
  "canceled": false,
  "clientId": "5e9ab369ed6377000d23d5b4",
  "accountId": "5e9ab369ed6377000d23d599",
  "organizationId": "5e9ab369ed6377000d23d59b",
  "_documentClient": {
    "id": "422d1fd5-d8e6-4635-8b16-107679a364f8",
    "name": "Rocket man",
    "country": "United Kingdom",
    "taxSubject": false,
    "isEndCustomer": false,
    "custom": {}
  },
  "_documentIssuer": {
    "id": "66953056-3253-41e8-9657-59bd9c254dda",
    "name": "International Space Agency",
    "address": "Rocket street 1",
    "address2": "",
    "city": "Brussels",
    "zip": "10000",
    "state": "",
    "country": "Belgium",
    "countryAlpha2Code": "BE",
    "taxNumber": "10489185",
    "taxSubject": true,
    "companyNumber": "0987654321",
    "IBAN": "GB49 REVO 0099 6979 5754 56",
    "bank": "Revolut ltd",
    "SWIFT": "",
    "website": "https://spaceinvoices.com",
    "email": "info@spaceinvoices.com",
    "phone": "+32 466 903 942",
    "custom": {}
  },
  "_documentItems": [
    {
      "id": "8946edb4-946e-4aed-bebd-299b74c3b663",
      "itemId": "5e9a22366d3a80000e8797b0",
      "name": "Space suit",
      "description": "",
      "price": 1000,
      "quantity": 2,
      "discount": 0,
      "discountIsAmount": false,
      "unit": "Item",
      "isSeparator": false,
      "total": 2000,
      "totalWithTax": 2420,
      "totalDiscount": 0,
      "totalTax": 420,
      "_documentItemTaxes": [
        {
          "id": "508cae6c-2b28-4607-8a95-9a3066d6077f",
          "taxId": "5e9ac7df1ccbec000de73263",
          "name": "Belasting over de toegevoegde waarde",
          "abbreviation": "BTW",
          "rate": 21,
          "recoverable": true
          "reverseCharged": false,
          "compound": false,
        }
      ],
      "custom": {},
    }
  ],
  "note": "Please pay to bank account GB49 REVO 0099 6979 5754 56.\nWhen paying please use reference 2020-00001.\n\nThank you for your business",
  "signature": "International Space Agency",
  "footer": "International Space Agency, Rocket street 1, 10000 Brussels, Belgium, tax num.: 10489185, company num.: 0987654321",
  "documentIds": [],
  "decimalPlaces": 4,
  "total": 2000,
  "totalWithTax": 2420,
  "totalDiscount": 0,
  "totalPaid": 0,
  "totalDue": 2420,
  "paidInFull": false,
  "hasUnit": true,
  "sentSnailMail": false,
  "_documentTaxes": [
    {
      "tax": 21,
      "taxId": "5e9ac7df1ccbec000de73263",
      "base": 2000,
      "totalTax": 420
    }
  ],
  "_documentReverseTaxes": [],
  "_documentConversionRate": [],
  "isValidEslog": false,
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z"
}

This example demonstrates the process of creating an invoice providing minimal data.

HTTP Request

POST https://api.spaceinvoices.com/v1/organizations/:id/documents

Route parameters

id string required
ID of the Organization on which the Document is being created


Properties

number string default YYYY-0000n+1
Document number.
Must be unique for each Document type in Organization.


type string default invoice
Type of document, one of invoice, estimate, advance, credit-note, delivery-note.
Certain Document property rules behave differently depending on document type.
Can't be updated.


date date default today
Date Document was created/issued.


dateDue date default today + default due days
Date invoice is due.
Auto populated using Organization's default due days invoice_dueDays from today.
Only present if type=invoice.


dateService date default today
Date the service was started or conducted.
Only present if type=invoice.


dateServiceTo date
The date the service ends if multi-day service.
Only present if type=invoice.


dateValidTill date default today + default valid till days
Date the estimate is valid until.
Auto populated using Organization's default days valid until estimate_validTillDays from today.
Only present if type=estimate.


datePaid date default today
Date the advance was paid on.
Only present if type=advance.


reference string
Reference number of document Unique per Document type on Organization. Can be used for payment reference where Document number not in the appropriate format.


draft boolean default false
If the document is a draft.
If set to false the property cannot go back to true.
Only settable if type=invoice.


currencyId string
ISO 4217 currency code. Wikipedia
If not provided, the Organization's default currency is used.


clientId string
ID reference to the Organization's Client.
If provided _documentClient object gets populated using referenced Client.


_documentClient object
Document Client data.
Property is optional if clientId is provided.
If populated based on clientId reference any key defined in this object will take precedence.
If clientId is not provided and email is set will attempt to match client in the database based on email. If clientId is not provided, the data in the object is saved to the Organization's Clients, clientId is populated with saved Client.

toggle child attributes

name string required
Name of Client.
Optional if clientId provided on Document.


address string
Address.


address2 string
Address additional.


city string
City.


zip string
Zip/postal code.


state string
State or region.


country string
Country.


taxNumber string
Organization VAT / GST / sales tax or similar tax number.


taxSubject boolean
Indicates if the Client is subject to tax.


companyNumber string
Organization registration or similar number.


IBAN string
Bank account number.


bank string
Bank name.


SWIFT string
Bank SWIFT/BIC.


website string
Website address.


email string
Contact email.
If provided and clientId not provided will be used to find matching Client to populate clientId.


phone string
Contact phone.


isEndCustomer boolean default false
Indicates if Client is end customer ie. person.


custom object
Custom data.
See Model custom data section for details.


_documentIssuer object
Document Issuer data.
Property is automatically populated with Organization data.
Any key that is provided in the object will take precedence, useful for per-document changes.

toggle child attributes

name string
Name.


address string


address2 string
Address additional.


city string


zip string
Zip / postal code.


state string
State or region.


country string


taxNumber string
Organization VAT / GST / sales tax or similar tax number.


taxSubject boolean
Indicates if the Organization is subject to tax.


companyNumber string
Organization registration or similar number.


IBAN string
Bank account number.


bank string
Bank name.


SWIFT string
Bank SWIFT/BIC.


website string
Website address.
Displayed on some PDF templates.


email string
Email.
Displayed on some PDF templates.


phone string
Phone.
Displayed on some PDF templates.


custom object
Custom data.
See Model custom data section for details.



_documentItems array required
Collection of Document Items.

toggle child attributes

itemId string
ID reference to the Organization's item.
If set and property load=true, the item properties are populated from the referenced item, any key provided here will take precedence.


name string required
Name of item.
Optional if isSeparator is set to true or if itemId or SKU is provided and load is true.


description
Description of the item.


price number
Price per single item.


priceGross number
Gross price per single item.
If provided price is calculated from it.


quantity number
Quantity of items.


discount number
Discount percent.
If discountIsAmount=true then it is regarded as a value discount instead of percent.


discountIsAmount boolean default false
Indicates if discount is value based instead of percent.


unit string
Unit of measurement for the item ie. Item, Service, Meter, etc.


SKU string
SKU of the Item, can reference the Organization's Item by SKU property.
If provided and itemId not provided and property load=true, the item properties are populated from the referenced item, any key that is provided will take precedence.


isSepatator boolean default false
Indicates if item is separator.
Used for visually separating line items and naming groups of line items.
If true all properties except name and description are dropped.


custom object
Custom data.
See Model custom data section for details.


_documentItemTaxes object
Collection of Document Item Taxes.

toggle definition

taxId string
ID reference to Organization's Tax.
If the property is provided rate, recoverable and compound properties are auto-populated. Note that the rate is chosen based on the date property of Document if Tax has multiple rates associated with it.


name string
Full name of tax.


abbreviation string
Abbreviation of tax, used for display.


rate number
Tax rate percent.
If provided, the API attempts to match the tax from the database and populate it.


classification string
Tax classification.
If provided and rate not provided, the API attempts to match tax by it from the database and populate it.


recoverable boolean
If the tax is recoverable.


reverseCharged boolean
If the tax is reverse (self) charged.
Reverse charged tax is not applied to totals and is added to the Document's reverse taxes.


compound boolean
If tax is compound.
Compound tax is calculated on top of the total with tax sum after other taxes that are applied to the Item.


save boolean unpersisted default false
If the item should be saved.
If true the item is saved to the Organization's collection of items. The document item is also populated with the item's ID in the itemId field. NOTE: Ignored if itemId is also provided.


custom object
Custom data.
See Model custom data section for details.


note string
Note for Document.
Populated with the Organization's default if not provided. May contain shortcode notations which get parsed to data on PDF or when parseForDisplay flag is provided.


signature string
Signature for the Document.
Populated with the Organization default if not provided. May contain shortcode notations which get parsed to data on PDF or when parseForDisplay flag is provided.


footer string
Footer for the Document.
Populated with the Organizaion's default if not provided. May contain shortcode notations which get parsed to data on PDF or when parseForDisplay flag is provided.


documentIds array
Collection of IDs of referenced Documents.
Used for stating Document references on PDFs.


uniqueId string
Used to prevent double issuing of the same Document in case of network errors.
Will throw error if Document with same value already exists.


decimalPlaces number default 4
Number of decimal places to which the Document items are trimmed and rounded in calculations.
Should be 4 in most cases.


validateEslog boolean
If the validation for Eslog format should throw an error.


payments array
Collection of related Payments.
Can be populated on create Document to create Payments as well.

toggle child attributes


type string required
Type of payment, one of bank, online, paypal, cash, card, crypto, coupon, other.


amount number
Payment amount. If not provided the full document amount will be used.


date date
Date of payment.


description string


Retrieve a Document

curl "https://api.spaceinvoices.com/v1/documents/5a3683ea12d5a67dd0ef2f4c" \
  -H "Authorization: LAUNCH_CODE"
spaceInvoices.documents
  .getById(documentId, queryParams)
  .then(function (document) {
    // Use the document
  });
<?php
  Spaceinvoices\Documents::getById("DOCUMENT_ID", $filter);
?>

Returns:

{
  "id": "5e9ab369ed6377000d23d5b5",
  "number": "2020-00001",
  "type": "invoice",
  "date": "2020-04-18T07:59:37.902Z",
  "dateDue": "2020-05-18T00:00:00.000Z",
  "dateService": "2020-04-18T07:59:37.902Z",
  "dateServiceTo": "2020-04-18T07:59:37.902Z",
  "dateValidTill": "2020-05-18T00:00:00.000Z",
  "datePaid": "2020-04-18T07:59:37.902Z",
  "reference": "",
  "draft": false,
  "currencyId": "EUR",
  "canceled": false,
  "clientId": "5e9ab369ed6377000d23d5b4",
  "accountId": "5e9ab369ed6377000d23d599",
  "organizationId": "5e9ab369ed6377000d23d59b",
  "_documentClient": {
    "id": "422d1fd5-d8e6-4635-8b16-107679a364f8",
    "name": "Rocket man",
    "country": "United Kingdom",
    "taxSubject": false,
    "isEndCustomer": false,
    "custom": {}
  },
  "_documentIssuer": {
    "id": "66953056-3253-41e8-9657-59bd9c254dda",
    "name": "International Space Agency",
    "address": "Rocket street 1",
    "address2": "",
    "city": "Brussels",
    "zip": "10000",
    "state": "",
    "country": "Belgium",
    "countryAlpha2Code": "BE",
    "taxNumber": "10489185",
    "taxSubject": true,
    "companyNumber": "0987654321",
    "IBAN": "GB49 REVO 0099 6979 5754 56",
    "bank": "Revolut ltd",
    "SWIFT": "",
    "website": "https://spaceinvoices.com",
    "email": "info@spaceinvoices.com",
    "phone": "+32 466 903 942",
    "custom": {}
  },
  "_documentItems": [
    {
      "id": "8946edb4-946e-4aed-bebd-299b74c3b663",
      "itemId": "5e9a22366d3a80000e8797b0",
      "name": "Space suit",
      "description": "",
      "price": 1000,
      "quantity": 2,
      "discount": 0,
      "discountIsAmount": false,
      "unit": "Item",
      "isSeparator": false,
      "total": 2000,
      "totalWithTax": 2420,
      "totalDiscount": 0,
      "totalTax": 420,
      "_documentItemTaxes": [
        {
          "id": "508cae6c-2b28-4607-8a95-9a3066d6077f",
          "taxId": "5e9ac7df1ccbec000de73263",
          "name": "Belasting over de toegevoegde waarde",
          "abbreviation": "BTW",
          "rate": 21,
          "recoverable": true
          "reverseCharged": false,
          "compound": false,
        }
      ],
      "custom": {},
    }
  ],
  "note": "Please pay to bank account GB49 REVO 0099 6979 5754 56.\nWhen paying please use reference 2020-00001.\n\nThank you for your business",
  "signature": "International Space Agency",
  "footer": "International Space Agency, Rocket street 1, 10000 Brussels, Belgium, tax num.: 10489185, company num.: 0987654321",
  "documentIds": [],
  "decimalPlaces": 4,
  "total": 2000,
  "totalWithTax": 2420,
  "totalDiscount": 0,
  "totalPaid": 0,
  "totalDue": 2420,
  "paidInFull": false,
  "hasUnit": true,
  "sentSnailMail": false,
  "_documentTaxes": [
    {
      "tax": 21,
      "taxId": "5e9ac7df1ccbec000de73263",
      "base": 2000,
      "totalTax": 420
    }
  ],
  "_documentReverseTaxes": [],
  "_documentConversionRate": [],
  "isValidEslog": false,
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z"
}

HTTP Request

GET https://api.spaceinvoices.com/v1/documents/:id

Route parameters

id string required
ID of the Document being retrieved


parseSmartcodes boolean default true If smart codes should be parsed to their respective values when retrieving the document.


Update a Document

curl -X PUT "https://api.spaceinvoices.com/v1/documents/5a3683ea12d5a67dd0ef2f4c" \
  -H "Authorization: LAUNCH_CODE" \
  -d _documentClient[name]="Rocket Man" \
  -d _documentClient[country]="United Kingdom" \
  -d _documentItems[0][name]="Space suit" \
  -d _documentItems[0][quantity]=2 \
  -d _documentItems[0][unit]="Item" \
  -d _documentItems[0][price]="1000" \
  -d _documentItems[0][_documentItemTaxes][0][rate]=21
spaceInvoices.documents
  .edit(document.id, {...})
  .then(function (document) {
    // Use the document
  });
<?php
  Spaceinvoices\Documents::edit("DOCUMENT_ID", array(...));
?>

Returns:

{
  "id": "5e9ab369ed6377000d23d5b5",
  "number": "2020-00001",
  "type": "invoice",
  "date": "2020-04-18T07:59:37.902Z",
  "dateDue": "2020-05-18T00:00:00.000Z",
  "dateService": "2020-04-18T07:59:37.902Z",
  "dateServiceTo": "2020-04-18T07:59:37.902Z",
  "dateValidTill": "2020-05-18T00:00:00.000Z",
  "datePaid": "2020-04-18T07:59:37.902Z",
  "reference": "",
  "draft": false,
  "currencyId": "EUR",
  "canceled": false,
  "clientId": "5e9ab369ed6377000d23d5b4",
  "accountId": "5e9ab369ed6377000d23d599",
  "organizationId": "5e9ab369ed6377000d23d59b",
  "_documentClient": {
    "id": "422d1fd5-d8e6-4635-8b16-107679a364f8",
    "name": "Rocket man",
    "country": "United Kingdom",
    "taxSubject": false,
    "isEndCustomer": false,
    "custom": {}
  },
  "_documentIssuer": {
    "id": "66953056-3253-41e8-9657-59bd9c254dda",
    "name": "International Space Agency",
    "address": "Rocket street 1",
    "address2": "",
    "city": "Brussels",
    "zip": "10000",
    "state": "",
    "country": "Belgium",
    "countryAlpha2Code": "BE",
    "taxNumber": "10489185",
    "taxSubject": true,
    "companyNumber": "0987654321",
    "IBAN": "GB49 REVO 0099 6979 5754 56",
    "bank": "Revolut ltd",
    "SWIFT": "",
    "website": "https://spaceinvoices.com",
    "email": "info@spaceinvoices.com",
    "phone": "+32 466 903 942",
    "custom": {}
  },
  "_documentItems": [
    {
      "id": "8946edb4-946e-4aed-bebd-299b74c3b663",
      "itemId": "5e9a22366d3a80000e8797b0",
      "name": "Space suit",
      "description": "",
      "price": 1000,
      "quantity": 2,
      "discount": 0,
      "discountIsAmount": false,
      "unit": "Item",
      "isSeparator": false,
      "total": 2000,
      "totalWithTax": 2420,
      "totalDiscount": 0,
      "totalTax": 420,
      "_documentItemTaxes": [
        {
          "id": "508cae6c-2b28-4607-8a95-9a3066d6077f",
          "taxId": "5e9ac7df1ccbec000de73263",
          "name": "Belasting over de toegevoegde waarde",
          "abbreviation": "BTW",
          "rate": 21,
          "recoverable": true
          "reverseCharged": false,
          "compound": false,
        }
      ],
      "custom": {},
    }
  ],
  "note": "Please pay to bank account GB49 REVO 0099 6979 5754 56.\nWhen paying please use reference 2020-00001.\n\nThank you for your business",
  "signature": "International Space Agency",
  "footer": "International Space Agency, Rocket street 1, 10000 Brussels, Belgium, tax num.: 10489185, company num.: 0987654321",
  "documentIds": [],
  "decimalPlaces": 4,
  "total": 2000,
  "totalWithTax": 2420,
  "totalDiscount": 0,
  "totalPaid": 0,
  "totalDue": 2420,
  "paidInFull": false,
  "hasUnit": true,
  "sentSnailMail": false,
  "_documentTaxes": [
    {
      "tax": 21,
      "taxId": "5e9ac7df1ccbec000de73263",
      "base": 2000,
      "totalTax": 420
    }
  ],
  "_documentReverseTaxes": [],
  "_documentConversionRate": [],
  "isValidEslog": false,
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z"
}

Unlike other models, the Document model performs a full replace when updating instead of a partial update requiring the full object data to be posted.

HTTP Request

PUT https://api.spaceinvoices.com/v1/documents/:id

Route parameters

id string required
ID of the Document being updated


Properties

number string
Document number.
Must be unique for each Document type in Organization.


type string
Type of document, one of invoice, estimate, advance, credit-note, delivery-note.
Certain Document property rules behave differently depending on document type.
Can't be updated.


date date
Date Document was created/issued.


dateDue date
Date invoice is due.
Auto populated using Organization's default due days invoice_dueDays from today.
Only present if type=invoice.


dateService date
Date the service was started or conducted.
Only present if type=invoice.


dateServiceTo date
The date the service ends if multi-day service.
Only present if type=invoice.


dateValidTill date
Date the estimate is valid until.
Auto populated using Organization's default days valid until estimate_validTillDays from today.
Only present if type=estimate.


datePaid date
Date the advance was paid on.
Only present if type=advance.


reference string
Reference number of document Unique per Document type on Organization. Can be used for payment reference where Document number not in the appropriate format.


draft boolean
If the document is a draft.
If set to false the property cannot go back to true.
Only settable if type=invoice.


currencyId string
ISO 4217 currency code. Wikipedia
If not provided, the Organization's default currency is used.


clientId string
ID reference to the Organization's Client.
If provided _documentClient object gets populated using referenced Client.


_documentClient object
Document Client data.
Property is optional if clientId is provided.
If populated based on clientId reference any key defined in this object will take precedence.
If clientId is not provided and email is set will attempt to match client in the database based on email. If clientId is not provided, the data in the object is saved to the Organization's Clients, clientId is populated with saved Client.

toggle child attributes

name string
Name of Client.
Optional if clientId provided on Document.


address string
Address.


address2 string
Address additional.


city string
City.


zip string
Zip/postal code.


state string
State or region.


country string
Country.


taxNumber string
Organization VAT / GST / sales tax or similar tax number.


taxSubject boolean
Indicates if the Client is subject to tax.


companyNumber string
Organization registration or similar number.


IBAN string
Bank account number.


bank string
Bank name.


SWIFT string
Bank SWIFT/BIC.


website string
Website address.


email string
Contact email.
If provided and clientId not provided will be used to find matching Client to populate clientId.


phone string
Contact phone.


isEndCustomer boolean
Indicates if Client is end customer ie. person.


custom object
Custom data.
See Model custom data section for details.


_documentIssuer object
Document Issuer data.
Property is automatically populated with Organization data.
Any key that is provided in the object will take precedence, useful for per-document changes.

toggle child attributes

name string
Name.


address string


address2 string
Address additional.


city string


zip string
Zip / postal code.


state string
State or region.


country string


taxNumber string
Organization VAT / GST / sales tax or similar tax number.


taxSubject boolean
Indicates if the Organization is subject to tax.


companyNumber string
Organization registration or similar number.


IBAN string
Bank account number.


bank string
Bank name.


SWIFT string
Bank SWIFT/BIC.


website string
Website address.
Displayed on some PDF templates.


email string
Email.
Displayed on some PDF templates.


phone string
Phone.
Displayed on some PDF templates.


custom object
Custom data.
See Model custom data section for details.



_documentItems array
Collection of Document Items.

toggle child attributes

itemId string
ID reference to the Organization's item.
If set and property load=true, the item properties are populated from the referenced item, any key provided here will take precedence.


name string
Name of item.
Optional if isSeparator is set to true or if itemId or SKU is provided and load is true.


description
Description of the item.


price number
Price per single item.


priceGross number
Gross price per single item.
If provided price is calculated from it.


quantity number
Quantity of items.


discount number
Discount percent.
If discountIsAmount=true then it is regarded as a value discount instead of percent.


discountIsAmount boolean
Indicates if discount is value based instead of percent.


unit string
Unit of measurement for the item ie. Item, Service, Meter, etc.


SKU string
SKU of the Item, can reference the Organization's Item by SKU property.
If provided and itemId not provided and property load=true, the item properties are populated from the referenced item, any key that is provided will take precedence.


isSepatator boolean
Indicates if item is separator.
Used for visually separating line items and naming groups of line items.
If true all properties except name and description are dropped.


custom object
Custom data.
See Model custom data section for details.


_documentItemTaxes object
Collection of Document Item Taxes.

toggle definition

taxId string
ID reference to Organization's Tax.
If the property is provided rate, recoverable and compound properties are auto-populated. Note that the rate is chosen based on the date property of Document if Tax has multiple rates associated with it.


name string
Full name of tax.


abbreviation string
Abbreviation of tax, used for display.


rate number
Tax rate percent.
If provided, the API attempts to match the tax from the database and populate it.


classification string
Tax classification.
If provided and rate not provided, the API attempts to match tax by it from the database and populate it.


recoverable boolean
If the tax is recoverable.


reverseCharged boolean
If the tax is reverse (self) charged.
Reverse charged tax is not applied to totals and is added to the Document's reverse taxes.


compound boolean
If tax is compound.
Compound tax is calculated on top of the total with tax sum after other taxes that are applied to the Item.


save boolean unpersisted
If the item should be saved.
If true the item is saved to the Organization's collection of items. The document item is also populated with the item's ID in the itemId field. NOTE: Ignored if itemId is also provided.


custom object
Custom data.
See Model custom data section for details.


note string
Note for Document.
Populated with the Organization's default if not provided. May contain shortcode notations which get parsed to data on PDF or when parseForDisplay flag is provided.


signature string
Signature for the Document.
Populated with the Organization default if not provided. May contain shortcode notations which get parsed to data on PDF or when parseForDisplay flag is provided.


footer string
Footer for the Document.
Populated with the Organizaion's default if not provided. May contain shortcode notations which get parsed to data on PDF or when parseForDisplay flag is provided.


documentIds array
Collection of IDs of referenced Documents.
Used for stating Document references on PDFs.


uniqueId string
Used to prevent double issuing of the same Document in case of network errors.
Will throw error if Document with same value already exists.


decimalPlaces number
Number of decimal places to which the Document items are trimmed and rounded in calculations.
Should be 4 in most cases.


validateEslog boolean
If the validation for Eslog format should throw an error.


payments array
Collection of related Payments.
Can be included, see Filters section for details. Can be populated on create Document to create Payments as well.


Delete a Document

curl -X DELETE "https://api.spaceinvoices.com/v1/documents/5a3683ea12d5a67dd0ef2f4c" \
  -H "Authorization: LAUNCH_CODE"
spaceInvoices.documents.delete(documentId).then(function (count) {
  console.log(count);
});
<?php
  Spaceinvoices\Documents::delete("DOCUMENT_ID");
?>

Returns:

{
  "count": 1
}

HTTP Request

DELETE https://api.spaceinvoices.com/v1/documents/:id

Route parameters

id string required
ID of the Document being deleted


Not permitted to delete if type=invoice of if the document was fiscally verified, a cancelation can be performed instead.

HTTP Request

DELETE https://api.spaceinvoices.com/v1/documents/:id

Route parameters

id string required
ID of Document to delete.


List all Documents

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/documents?filter[where][type]=invoice" \
  -H "Authorization: LAUNCH_CODE"
var queryParams = {
  filter: {
    where: {
      type: "invoice",
    },
  },
};

spaceInvoices.documents
  .list(organizationId, queryParams)
  .then(function (documents) {
    // Use the array of documents
  });
<?php
  Spaceinvoices\Documents::find("ORGANIZATION_ID", array(
    "filter" => array(
      "where" => array(
        "type" => "invoice"
      )
    )
  ));
?>

Returns:

[{
  "id": "5e9ab369ed6377000d23d5b5",
  "number": "2020-00001",
  "type": "invoice",
  "date": "2020-04-18T07:59:37.902Z",
  "dateDue": "2020-05-18T00:00:00.000Z",
  "dateService": "2020-04-18T07:59:37.902Z",
  "dateServiceTo": "2020-04-18T07:59:37.902Z",
  "dateValidTill": "2020-05-18T00:00:00.000Z",
  "datePaid": "2020-04-18T07:59:37.902Z",
  "reference": "",
  "draft": false,
  "currencyId": "EUR",
  "canceled": false,
  "clientId": "5e9ab369ed6377000d23d5b4",
  "accountId": "5e9ab369ed6377000d23d599",
  "organizationId": "5e9ab369ed6377000d23d59b",
  "_documentClient": {
    "id": "422d1fd5-d8e6-4635-8b16-107679a364f8",
    "name": "Rocket man",
    "country": "United Kingdom",
    "taxSubject": false,
    "isEndCustomer": false,
    "custom": {}
  },
  "_documentIssuer": {
    "id": "66953056-3253-41e8-9657-59bd9c254dda",
    "name": "International Space Agency",
    "address": "Rocket street 1",
    "address2": "",
    "city": "Brussels",
    "zip": "10000",
    "state": "",
    "country": "Belgium",
    "countryAlpha2Code": "BE",
    "taxNumber": "10489185",
    "taxSubject": true,
    "companyNumber": "0987654321",
    "IBAN": "GB49 REVO 0099 6979 5754 56",
    "bank": "Revolut ltd",
    "SWIFT": "",
    "website": "https://spaceinvoices.com",
    "email": "info@spaceinvoices.com",
    "phone": "+32 466 903 942",
    "custom": {}
  },
  "_documentItems": [
    {
      "id": "8946edb4-946e-4aed-bebd-299b74c3b663",
      "itemId": "5e9a22366d3a80000e8797b0",
      "name": "Space suit",
      "description": "",
      "price": 1000,
      "quantity": 2,
      "discount": 0,
      "discountIsAmount": false,
      "unit": "Item",
      "isSeparator": false,
      "total": 2000,
      "totalWithTax": 2420,
      "totalDiscount": 0,
      "totalTax": 420,
      "_documentItemTaxes": [
        {
          "id": "508cae6c-2b28-4607-8a95-9a3066d6077f",
          "taxId": "5e9ac7df1ccbec000de73263",
          "name": "Belasting over de toegevoegde waarde",
          "abbreviation": "BTW",
          "rate": 21,
          "recoverable": true
          "reverseCharged": false,
          "compound": false,
        }
      ],
      "custom": {},
    }
  ],
  "note": "Please pay to bank account GB49 REVO 0099 6979 5754 56.\nWhen paying please use reference 2020-00001.\n\nThank you for your business",
  "signature": "International Space Agency",
  "footer": "International Space Agency, Rocket street 1, 10000 Brussels, Belgium, tax num.: 10489185, company num.: 0987654321",
  "documentIds": [],
  "decimalPlaces": 4,
  "total": 2000,
  "totalWithTax": 2420,
  "totalDiscount": 0,
  "totalPaid": 0,
  "totalDue": 2420,
  "paidInFull": false,
  "hasUnit": true,
  "sentSnailMail": false,
  "_documentTaxes": [
    {
      "tax": 21,
      "taxId": "5e9ac7df1ccbec000de73263",
      "base": 2000,
      "totalTax": 420
    }
  ],
  "_documentReverseTaxes": [],
  "_documentConversionRate": [],
  "isValidEslog": false,
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z"
}, ...]

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/documents

Route parameters

id string required
ID of the Organization on which the Document is being listed


filter object
Query filters. See Filters section for more details.


parseSmartcodes boolean default true
If smart codes should be parsed to their respective values when retrieving the documents.


Count all Documents

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/documents/count" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "count": 1
}

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/documents/count

Route parameters

id string required
ID of the Organization on which the documents are being counted


where object
Query where. See Where operators section of filters for more details.


Retrieve a Document PDF

curl "https://api.spaceinvoices.com/v1/documents/5a3683ea12d5a67dd0ef2f4c/pdf?l=en" \
  -H "Authorization: LAUNCH_CODE" \
  -o document.pdf
spaceInvoices.documents.getPdf(DocumentId, "en").then(function (pdf) {
  console.log(pdf);
});
<?php
  Spaceinvoices\Documents::getPdf("DOCUMENT_ID", "en");
?>

Returns:

PDF Buffer

This endpoint returns a document in PDF format.

The template of the document can be changed by setting the pdf_template in the Defaults. The language of the document is determined by the l flag. If no flag is provided, the organization's default locale is used. Currently, this setting doesn't affect the user-created content of the document, only the predefined data like table headers, etc. We are working on a way to enable that as well.

HTTP Request

GET https://api.spaceinvoices.com/v1/documents/:id/pdf?l=en

Route parameters

id string required
ID of the Document being retrieved as PDF.


language string
Language of the PDF
Supported language flags en, sl, de, it, es, fr, cz.
Defaults to Organization's locale.


Send a Document in Email

curl "https://api.spaceinvoices.com/v1/documents/5a3683ea12d5a67dd0ef2f4c/send" \
  -H "Authorization: LAUNCH_CODE" \
  -d recipients="rocketman@example.com" \
  -d message="You can find the document PDF in the attachment." \
  -d subject="Invoice"
spaceInvoices.documents
  .send("5a3683ea12d5a67dd0ef2f4c", {
    recipients: "rocketman@example.com",
    message: "You can find the document PDF in the attachment.",
    subject: "Invoice",
  })
  .then(function (result) {
    // Document send result
  });
<?php
  Spaceinvoices\Documents::send("5a3683ea12d5a67dd0ef2f4c", array(
    "recipients" => "rocketman@example.com",
    "message" => "You can find the document, number [document number], PDF in the attachment.",
    "subject" => "Invoice for service"
  ));
?>

Returns:

{
  "success": true
}

This endpoint allows sending an email with the Document PDF as an attachment.

Emails are sent from our regional addresses in the name of the organization sending it, a reply-to email property is set as the sender Account's email. While there are currently no styling options, we are developing an option for users to also provide an html template for the email. Linking one's domain for purposes of sending will also be possible. Please get in touch with us if you require specific functionality to be added in this context.

The delivery and open status of each sent Document can be tracked in the Document's Activities property.

HTTP Request

POST https://api.spaceinvoices.com/v1/documents/:id/send?l=en

Route parameters

id string required
ID of the Document being sent


l string
Language of attached Document PDF


Arguments

recipients string required
List of recipients separated with a comma.


message string required
Email message body.
Supports smart code notations which get parsed to data.


subject string required
Email subject.
Supports smart code notations which get parsed to data.


Cancel a Document

curl -X POST "https://api.spaceinvoices.com/v1/documents/5a3683ea12d5a67dd0ef2f4c/cancel" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "success": true
}

If the Document being canceled was fiscally verified a credit-note Document with a negative value will automatically be created in addition to this action.

HTTP Request

POST https://api.spaceinvoices.com/v1/documents/:id/cancel

Route parameters

id string required
ID of the Document being canceled


Un-cancel a Document

curl -X POST "https://api.spaceinvoices.com/v1/documents/5a3683ea12d5a67dd0ef2f4c/uncancel" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "success": true
}

It is not possible to cancel a Document that has been fiscally verified.

HTTP Request

POST https://api.spaceinvoices.com/v1/documents/:id/uncancel

Route parameters

id string required
ID of the Document being un-canceled


Mark a Document as sent

curl -X POST "https://api.spaceinvoices.com/v1/documents/5a3683ea12d5a67dd0ef2f4c/uncancel" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "success": true
}

Mark a document as sent using regular mail.
This action sets a Document's sentSnailMail property to true.

HTTP Request

POST https://api.spaceinvoices.com/v1/documents/:id/mark-sent

Route parameters

id string required
ID of the Document being marked as sent


Items

Endpoints:

  POST /v1/organizations/:id/items
   GET /v1/items/:id
   PUT /v1/items/:id
DELETE /v1/items/:id
   GET /v1/organizations/:id/items
   GET /v1/organizations/:id/items/count
   GET /v1/organizations/:id/search-items

Items represent items, services and any other things that an Organization can sell. They can be saved and later referenced using their unique ID or SKU values.

NOTE: While taxes are added to items by in taxIds property, they can also be referenced by their rate or classification value by providing either of the values as a property in _itemTaxes array which is a collection of objects, each object representing one tax reference. The API will attempt to find the best match.

The Item object

The Item object:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "organizationId": "5a3683ea12d5a67dd0ef2f4d",
  "name": "Space suit",
  "description": "Best in class suit made from durable composites.",
  "unit": "item",
  "price": 1000,
  "priceGross": undefined,
  "taxIds": ["5a3683ea12d5a67dd0ef2f4e"],
  "SKU": null,
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z",
  "taxes": [...]
}

Properties

id string readonly
Unique identifier.


organizationId string readonly
ID reference to Organization the Item belongs to.


name string


description string


unit string
Unit of measurement for Item/service.


price number
Net price of Item, optional if priceGross is provided.


priceGross number
Gross price of Item, optional if price is provided.
If provided takes precedence over price.


taxIds array
Collection of IDs referencing taxes that should be added to Item.
The referenced taxes will be used by default when Item is added to document.


SKU string
Unique Item identifier used to populate Items to documents.
Can't contain spaces.


custom object
Custom data.
See Model custom data section for details.


createdAt date readonly
When the instance was created.


updatedAt date readonly
When the instance was last updated.


taxes array readonly
Collection of related Taxes.
Can be included, see Filters section for details.


Create an Item

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/items" \
  -H "Authorization: LAUNCH_CODE" \
  -d name="Space suit" \
  -d description="Best in class suit made from durable composites." \
  -d unit="item" \
  -d price=1000 \
  -d taxIds[]="5a3683ea12d5a67dd0ef2f4e"
spaceInvoices.items
  .create(organizationId, {
    name: "Space suit",
    description: "Best in class suit made from durable composites.",
    unit: "item",
    price: 1000,
    taxIds: ["5a3683ea12d5a67dd0ef2f4e"],
  })
  .then(function (item) {
    // Use the item
  });
<?php
  Spaceinvoices\Items::create("ORG_ID", array(
    "name" => "Space suit",
    "description" => "Best in class suit made from durable composites.",
    "unit" => "item",
    "price" => 1000,
    "taxId" => ["5a3683ea12d5a67dd0ef2f4e"]
  ));
?>

Returns:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "organizationId": "5a3683ea12d5a67dd0ef2f4d",
  "name": "Space suit",
  "description": "Best in class suit made from durable composites.",
  "unit": "item",
  "price": 1000,
  "taxIds": ["5a3683ea12d5a67dd0ef2f4e"],
  "SKU": null,
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z",
}

HTTP Request

POST https://api.spaceinvoices.com/v1/organizations/:id/items

Route parameters

id string required
ID of the Organization on which the Item is being created


Properties

name string required


description string


unit string
Unit of measurement for Item/service.


price number
Net price of Item, optional if priceGross is provided.


priceGross number
Gross price of Item, optional if price is provided.
If provided takes precedence over price.


taxIds array
Collection of IDs referencing taxes that should be added to Item.
The referenced taxes will be used by default when Item is added to document.


_itemTaxes array
Collection of objects to reference taxes.
Used as convenience feature to avoid expricitly referencing taxes by their IDs, instead by classification or rate.

toggle child attributes


rate number
Rate of tax to match by.
Optional if classification is provided.


classification string
Classification of tax to match by.
Optional if rate is provided.


SKU string
Unique Item identifier used to populate Items to documents.
Can't contain spaces.


custom object
Custom data.
See Model custom data section for details.


Retrieve an Item

curl "https://api.spaceinvoices.com/v1/items/5e9ab369ed6377000d23d5b5" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "organizationId": "5a3683ea12d5a67dd0ef2f4d",
  "name": "Space suit",
  "description": "Best in class suit made from durable composites.",
  "unit": "item",
  "price": 1000,
  "taxIds": ["5a3683ea12d5a67dd0ef2f4e"],
  "SKU": null,
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z",
}

HTTP Request

GET https://api.spaceinvoices.com/v1/items/:id

Route parameters

id string required
ID of the Item being retrieved


Update an Item

curl -X PUT "https://api.spaceinvoices.com/v1/items/5a3683ea12d5a67dd0ef2f4c" \
  -H "Authorization: LAUNCH_CODE" \
  -d name="Space suit" \
  -d description="Best in class suit made from durable composites." \
  -d unit="item" \
  -d price=1000 \
  -d taxIds[]="5a3683ea12d5a67dd0ef2f4e"
spaceInvoices.items
  .edit("5a3683ea12d5a67dd0ef2f4c", {
    name: "Space suit",
    description: "Best in class suit made from durable composites.",
    unit: "item",
    price: 1000,
    taxIds: [taxId],
  })
  .then(function (item) {
    // Use the item
  });
<?php
  Spaceinvoices\Items::edit("5a3683ea12d5a67dd0ef2f4c", array(
    "name" => "Space suit",
    "description" => "Best in class suit made from durable composites.",
    "unit" => "item",
    "price" => 1000,
    "taxes" => ["5a3683ea12d5a67dd0ef2f4e"]
  ));
?>

Returns:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "organizationId": "5a3683ea12d5a67dd0ef2f4d",
  "name": "Space suit",
  "description": "Best in class suit made from durable composites.",
  "unit": "item",
  "price": 1000,
  "taxIds": ["5a3683ea12d5a67dd0ef2f4e"],
  "SKU": null,
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z",
}

Unlike other models, the Item model performs a full replace when updating instead of a partial update requiring the full object data to be posted.

HTTP Request

PUT https://api.spaceinvoices.com/v1/items/:id

Route parameters

id string required
ID of the Item being updated


Properties

name string required


description string


unit string
Unit of measurement for Item/service.


price number
Net price of Item, optional if priceGross is provided.


priceGross number
Gross price of Item, optional if price is provided.
If provided takes precedence over price.


taxIds array
Collection of IDs referencing taxes that should be added to Item.
The referenced taxes will be used by default when Item is added to document.


_itemTaxes array
Collection of objects to reference taxes.
Used as convenience feature to avoid expricitly referencing taxes by their IDs, instead by classification or rate.

toggle child attributes


rate number
Rate of tax to match by.
Optional if classification is provided.


classification string
Classification of tax to match by.
Optional if rate is provided.


SKU string
Unique Item identifier used to populate Items to documents.
Can't contain spaces.


custom object
Custom data.
See Model custom data section for details.


Delete an Item

curl -X DELETE "https://api.spaceinvoices.com/v1/items/5a3683ea12d5a67dd0ef2f4c" \
  -H "Authorization: LAUNCH_CODE"
spaceInvoices.items.delete("5a3683ea12d5a67dd0ef2f4c").then(function (count) {
  // Deleted count
});
<?php
  Spaceinvoices\Items::delete("5a3683ea12d5a67dd0ef2f4c");
?>

Returns:

{
  "count": 1
}

HTTP Request

DELETE https://api.spaceinvoices.com/v1/items/:id

Route parameters

id string required
ID of the Item being deleted


List all Items

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/items" \
  -H "Authorization: LAUNCH_CODE"
spaceInvoices.items.list("ORG_ID").then(function (items) {
  // Use the items
});
<?php
  Spaceinvoices\Items::find("ORG_ID");
?>

Returns:

[{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "organizationId": "5a3683ea12d5a67dd0ef2f4d",
  "name": "Space suit",
  "description": "Best in class suit made from durable composites.",
  "unit": "item",
  "price": 1000,
  "taxIds": ["5a3683ea12d5a67dd0ef2f4e"],
  "SKU": null,
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z",
}, ...]

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/items

Route parameters

id string required
ID of the Organization on which the items are being listed


filter object
Query filters. See Filters section for more details.


Count all Items

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/items/count" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "count": 1
}

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/items/count

Route parameters

id string required
ID of the Organization on which the items are being counted


where object
Query where. See Where operators section of filters for more details.


Search all Items

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/items/search?term=Space" \
  -H "Authorization: LAUNCH_CODE"
spaceInvoices.items.search("ORG_ID", "space").then(function (items) {
  // Use the items
});
<?php
  Spaceinvoices\Items::search("ORG_ID", "space");
?>

Returns:

[{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "organizationId": "5a3683ea12d5a67dd0ef2f4d",
  "name": "Space suit",
  "description": "Best in class suit made from durable composites.",
  "unit": "item",
  "price": 1000,
  "taxIds": ["5a3683ea12d5a67dd0ef2f4e"],
  "SKU": null,
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z",
}, ...]

Convenience method for searching items by multiple fields.

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/items/search?term=:term

Route parameters

id string required
ID of the Organization on which te items are being searched


term string required
Term to search for.


Organizations

Endpoints:

  POST /v1/accounts/:id/organizations
   GET /v1/organizations/:id
 PATCH /v1/organizations/:id
   GET /v1/accounts/:id/organizations
   GET /v1/accounts/:id/organizations/count
  POST /v1/organizations/images
DELETE /v1/organizations/images
   GET /v1/organizations/images
  POST /v1/organizations/:id/deactivate
  POST /v1/organizations/:id/activate
   GET /v1/organizations/:id/export
  POST /v1/organizations/:id/invite
   GET /v1/organizations/:id/accountorganizations
   GET /v1/organizations/:id/stats

Any given Account can control multiple Organizations. They may either create these Organizations themselves or other users may assign access rights of existing organizations to these given accounts.

This is especially useful when there is a need to manage multiple organizations, as they are created for users that might signup for a certain product.

Most of the models created though the API are related to an Organization instance.

The Organization object

The Organization object:

{
  "id": "5e9e92107f186e000eda09cf",
  "name": "International Space Agency",
  "address": "Rocket street 1",
  "address2": "",
  "city": "Brussels",
  "zip": "10000",
  "state": "",
  "country": "Belgium",
  "countryAlpha2Code": "BE",
  "taxNumber": "10489185",
  "taxSubject": true,
  "companyNumber": "0987654321",
  "IBAN": "GB49 REVO 0099 6979 5754 56",
  "bank": "Revolut ltd",
  "SWIFT": "",
  "website": "https://spaceinvoices.com",
  "email": "info@spaceinvoices.com",
  "phone": "+32 466 903 942",
  "locale": "en",
  "timezone": "CEDT",
  "active": true,
  "size": undefined,
  "industry": undefined,
  "activatedAt": "2020-04-18T07:59:37.938Z",
  "deactivatedAt": "2020-04-18T07:59:37.938Z",
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z",
  "_defaults": [...]
}

Properties

id string readonly
Unique identifier.


name string


address string


address2 string
Address additional.


city string


zip string
Zip / postal code.


state string
State or region.


country any
The value is used to apply some smart defaults to the organization being created including country default tax rates, locale, timezone and country alpha 2 ISO code. We recommend providing either the english language or native name of country to ensure this function, but this is not the required form and is not validated as such.


countryAlpha2Code string readonly
Country ISO alpha-2 code. Wikipedia. API automatically parses Organization address details to determine the Organization's country and populates property based on the result.


taxNumber string
Organization VAT / GST / sales tax or similar tax number.


taxSubject boolean
Indicates if the Organization is subject to tax.


companyNumber string
Organization registration or similar number.


IBAN string
Bank account number.


bank string
Bank name.


SWIFT string
Bank SWIFT/BIC.


website string
Website address.
Displayed on some PDF templates.


email string
Email.
Displayed on some PDF templates.


phone string
Phone.
Displayed on some PDF templates.


locale string
Default locale of Organization.
Defaults to the country's locale or en as fallback.
ISO 639-1 locale code. Wikipedia
Affects language of default texts and system messages, PDFs and other translatable resources.


timezone string
ISO timezone of Organization.
Populated with country's timezone when instance created.


custom object
Custom data.
See Model custom data section for details.


active boolean readonly
If Organization is activated.
Actions on a deactivated Organization are not possible.


activatedAt date readonly
When the Organization was last activated.


deactivatedAt date readonly
When the Organization was last deactivated.


createdAt date readonly
When the instance was created.


updatedAt date readonly
When the instance was last updated.


_defaults array readonly
Collection of related Defaults.
Automatically included.


Create an Organization

curl "https://api.spaceinvoices.com/v1/accounts/ACCOUNT_ID/organizations" \
  -H "Authorization: LAUNCH_CODE" \
  -d name="International Space Agency" \
  -d address="Rocket Road 1" \
  -d city="Brussels" \
  -d zip="10000" \
  -d country="Belgium" \
  -d IBAN="GB95 REVO 1234 5678 9012 345" \
  -d bank="Revolut Ltd"
spaceInvoices.organizations
  .create("5a3683ea12d5a67dd0ef2f4d", {
    name: "International Space Agency",
    address: "Rocket Road 1",
    city: "Brussels",
    zip: "10000",
    country: "Belgium",
    IBAN: "123454321 123454321",
    bank: "Revolut Ltd",
  })
  .then(function (organization) {
    // Use the organization
  });
<?php
  Spaceinvoices\Organizations::create("5a3683ea12d5a67dd0ef2f4d", array(
    "name" => "International Space Agency",
    "address" => "Rocket Road 1",
    "city" => "Brussels",
    "zip" => "10000",
    "country" => "Belgium",
    "IBAN" => "123454321 123454321",
    "bank" => "Revolut Ltd"
  ));
?>

Returns:

{
  "id": "5e9e92107f186e000eda09cf",
  "name": "International Space Agency",
  "address": "Rocket street 1",
  "address2": "",
  "city": "Brussels",
  "zip": "10000",
  "state": "",
  "country": "Belgium",
  "countryAlpha2Code": "BE",
  "taxNumber": "10489185",
  "taxSubject": true,
  "companyNumber": "0987654321",
  "IBAN": "GB49 REVO 0099 6979 5754 56",
  "bank": "Revolut ltd",
  "SWIFT": "",
  "website": "https://spaceinvoices.com",
  "email": "info@spaceinvoices.com",
  "phone": "+32 466 903 942",
  "locale": "en",
  "timezone": "CEDT",
  "active": true,
  "activatedAt": "2020-04-18T07:59:37.938Z",
  "deactivatedAt": "2020-04-18T07:59:37.938Z",
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z",
  "_defaults": [...]
}

HTTP Request

POST https://api.spaceinvoices.com/v1/accounts/:id/organizations

Route parameters

id string required
ID of the Account on which the Organization is being created


Properties

name string required


address string


address2 string
Address additional.


city string


zip string
Zip / postal code.


state string
State or region.


country any required
The value is used to apply some smart defaults to the organization being created including country default tax rates, locale, timezone and country alpha 2 ISO code. We recommend providing either the english language or native name of country to ensure this function, but this is not the required form and is not validated as such.


taxNumber string
Organization VAT / GST / sales tax or similar tax number.


taxSubject boolean
Indicates if the Organization is subject to tax.


companyNumber string
Organization registration or similar number.


IBAN string
Bank account number.


bank string
Bank name.


SWIFT string
Bank SWIFT/BIC.


website string
Website address.
Displayed on some PDF templates.


email string
Email.
Displayed on some PDF templates.


phone string
Phone.
Displayed on some PDF templates.


locale string
Default locale of Organization.
Defaults to the country's locale or en as fallback.
ISO 639-1 locale code. Wikipedia
Affects language of default texts and system messages, PDFs and other translatable resources.


timezone string
ISO timezone of Organization.
Populated with country's timezone when instance created.


custom object
Custom data.
See Model custom data section for details.


Retrieve an Organization

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID" \
  -H "Authorization: LAUNCH_CODE"
spaceInvoices.organizations.getById("ORG_ID").then(function (organization) {
  // Use the organization
});
<?php
  Spaceinvoices\Organizations::getById("ORG_ID");
?>

Returns:

{
  "id": "5e9e92107f186e000eda09cf",
  "name": "International Space Agency",
  "address": "Rocket street 1",
  "address2": "",
  "city": "Brussels",
  "zip": "10000",
  "state": "",
  "country": "Belgium",
  "countryAlpha2Code": "BE",
  "taxNumber": "10489185",
  "taxSubject": true,
  "companyNumber": "0987654321",
  "IBAN": "GB49 REVO 0099 6979 5754 56",
  "bank": "Revolut ltd",
  "SWIFT": "",
  "website": "https://spaceinvoices.com",
  "email": "info@spaceinvoices.com",
  "phone": "+32 466 903 942",
  "locale": "en",
  "timezone": "CEDT",
  "active": true,
  "activatedAt": "2020-04-18T07:59:37.938Z",
  "deactivatedAt": "2020-04-18T07:59:37.938Z",
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z",
  "_defaults": [...]
}

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id

Route parameters

id string required
ID of the Organization being retrieved


Update an Organization

curl -X PATCH "https://api.spaceinvoices.com/v1/organizations/ORG_ID" \
  -H "Authorization: LAUNCH_CODE" \
  -d name="International Space Agency"

Returns:

{
  "id": "5e9e92107f186e000eda09cf",
  "name": "International Space Agency",
  "address": "Rocket street 1",
  "address2": "",
  "city": "Brussels",
  "zip": "10000",
  "state": "",
  "country": "Belgium",
  "countryAlpha2Code": "BE",
  "taxNumber": "10489185",
  "taxSubject": true,
  "companyNumber": "0987654321",
  "IBAN": "GB49 REVO 0099 6979 5754 56",
  "bank": "Revolut ltd",
  "SWIFT": "",
  "website": "https://spaceinvoices.com",
  "email": "info@spaceinvoices.com",
  "phone": "+32 466 903 942",
  "locale": "en",
  "timezone": "CEDT",
  "active": true,
  "activatedAt": "2020-04-18T07:59:37.938Z",
  "deactivatedAt": "2020-04-18T07:59:37.938Z",
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z",
  "_defaults": [...]
}

HTTP Request

PATCH https://api.spaceinvoices.com/v1/organizations/:id

Route parameters

id string required
ID of the Organization being updated


Properties

name string


address string


address2 string
Address additional.


city string


zip string
Zip / postal code.


state string
State or region.


country any
The value is used to apply some smart defaults to the organization being created including country default tax rates, locale, timezone and country alpha 2 ISO code. We recommend providing either the english language or native name of country to ensure this function, but this is not the required form and is not validated as such.


taxNumber string
Organization VAT / GST / sales tax or similar tax number.


taxSubject boolean
Indicates if the Organization is subject to tax.


companyNumber string
Organization registration or similar number.


IBAN string
Bank account number.


bank string
Bank name.


SWIFT string
Bank SWIFT/BIC.


website string
Website address.
Displayed on some PDF templates.


email string
Email.
Displayed on some PDF templates.


phone string
Phone.
Displayed on some PDF templates.


locale string
Default locale of Organization.
Defaults to the country's locale or en as fallback.
ISO 639-1 locale code. Wikipedia
Affects language of default texts and system messages, PDFs and other translatable resources.


timezone string
ISO timezone of Organization.
Populated with country's timezone when instance created.


custom object
Custom data.
See Model custom data section for details.


List all Organizations

curl "https://api.spaceinvoices.com/v1/accounts/ACCOUNT_ID/organizations" \
  -H "Authorization: LAUNCH_CODE"
spaceInvoices.organizations.list("ACCOUNT_ID").then(function (organization) {
  // Use the organizations
});
<?php
  Spaceinvoices\Organizations::find("ACCOUNT_ID");
?>

Returns:

[{
  "id": "5e9e92107f186e000eda09cf",
  "name": "International Space Agency",
  "address": "Rocket street 1",
  "address2": "",
  "city": "Brussels",
  "zip": "10000",
  "state": "",
  "country": "Belgium",
  "countryAlpha2Code": "BE",
  "taxNumber": "10489185",
  "taxSubject": true,
  "companyNumber": "0987654321",
  "IBAN": "GB49 REVO 0099 6979 5754 56",
  "bank": "Revolut ltd",
  "SWIFT": "",
  "website": "https://spaceinvoices.com",
  "email": "info@spaceinvoices.com",
  "phone": "+32 466 903 942",
  "locale": "en",
  "timezone": "CEDT",
  "active": true,
  "activatedAt": "2020-04-18T07:59:37.938Z",
  "deactivatedAt": "2020-04-18T07:59:37.938Z",
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z",
  "_defaults": [...]
}, ...]

HTTP Request

GET https://api.spaceinvoices.com/v1/accounts/:id/organizations

Route parameters

id string required
ID of the Account on which the organizations are being listed


filter object
Query filters. See Filters section for more details.


Count all Organizations

curl "https://api.spaceinvoices.com/v1/accounts/ACCOUNT_ID/organizations/count" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "count": 1
}

HTTP Request

GET https://api.spaceinvoices.com/v1/accounts/:id/organizations/count

Route parameters

id string required
ID of the Account on which the organizations are being counted


where object
Query where. See Where operators section of filters for more details.


Upload Logo or Signature image to Organization

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/images?type=logo" \
  -H "Authorization: LAUNCH_CODE" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -F "file=@path_to_file.jpg"
spaceInvoices.organizations
  .uploadImage("ORG_ID", "path_to_file.jpg", "logo")
  .then(function (res) {
    // Success
  });
<?php
  Spaceinvoices\Organizations::uploadImage("ORG_ID", "path_to_file.jpg", "logo");
?>

Returns:

true

This endpoint allows the uploading of a Logo or a Signature image for a given organization. The image is then automatically used in all documents when generating a PDF.

To check if an organization has a logo or signature image set, we simply need to check an organization's _defaults object for keys containing image_logo or image_signature where the key is set to true.
The _defaults object is retrieved with the organization when querying it or by separately querying the Defaults.

HTTP Request

POST https://api.spaceinvoices.com/v1/organizations/:id/images?type=:type

Route parameters

id string required
ID of the Organization being uploaded to


type string required
The type of image being uploaded.
Valid options are logo or signature.


Properties

image file
The image payload to upload.
Must be sent as payload Content-Type: application/x-www-form-urlencoded.


Remove an image

curl -X DELETE "https://api.spaceinvoices.com/v1/organizations/ORG_ID/images?type=logo" \
  -H "Authorization: LAUNCH_CODE"

Returns:

true

Removes an image from the Organization and sets the image setting to false in Defaults.

HTTP Request

DELETE https://api.spaceinvoices.com/v1/organizations/:id/images?type=:type

Route parameters

id string required
ID of the Organization being removed from


type string required
The type of image being uploaded.
Valid options are logo or signature.


Download an image

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/images?type=logo" \
  -H "Authorization: LAUNCH_CODE"

Returns:

File Buffer

Downloads an image of the Organization.

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/images?type=:type

Route parameters

id string required
ID of the Organization being downloaded from


type string required
The type of image being uploaded.
Valid options are logo or signature.


Deactivate an Organization

curl -X POST "https://api.spaceinvoices.com/v1/organizations/ORG_ID/deactivate" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "success": true
}

Deactivates an active Organization. An Organization is active by default when created.

Actions on a deactivated Organization are not possible. The organization must be re-activated to enable actions.

Active organizations are counted towards the subscription total, minimum period for an Organization license is 1 month and is counted from date of activation.

HTTP Request

POST https://api.spaceinvoices.com/v1/organizations/:id/deactivate

Route parameters

id string required
ID of the Organization being deactivated


Activate an Organization

curl -X POST "https://api.spaceinvoices.com/v1/organizations/ORG_ID/activate" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "success": true
}

Activates a deactivated Organization. An Organization is active by default when created.

Deactivated organizations are not counted towards the subscription total, minimum period for an Organization license is 1 month and is counted from date of activation.

HTTP Request

POST https://api.spaceinvoices.com/v1/organizations/:id/activate

Route parameters

id string required
ID of the Organization being activated


Exporting data

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/export?type=document&where[type]=invoice&where[date][between][0]=2020-01-01&where[date][between][1]=2020-01-31" \
  -H "Authorization: LAUNCH_CODE"

Returns:

FILE Buffer

Exports certain data models to an excel file.

Where filters can be applied to limit the retrieved data by time, type, etc, see where operators in the filters section for more details.

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/export?type=:type

Route parameters

id string required
ID of the Organization being exported from


where object
Query where. See Where operators section of filters for more details.


type string required
Type of data being exported, one of document, client, item.


The access object

Endpoints:

  POST /v1/organizations/:id/invite
   GET /v1/organizations/:id/accountorganizations
DELETE /v1/accountorganizations/:id
  POST /v1/accountorganizations/:id/disable
  POST /v1/accountorganizations/:id/enable
  POST /v1/accountorganizations/:id/change-role

The Access object:

{
  "id": "5e9ab369ed6377000d23d5b5",
  "accountId": "5a3683ea12d5a67dd0ef2f4d",
  "role": "default",
  "active": true,
  "rejected": false,
  "disabled": false
}

Determins which Accounts have access to a specific Organization. Access can be granted, revoked and disabled.

Properties

id string readonly
Unique identifier.


organizationId string readonly
Related organization id.


accountId string
ID of Account with access.


role string
Role of Account, one of default, admin, readonly.
Currently the roles have more affect on actions in Apollo UI but will be expanded to more API actions as well.


active boolean readonly
If access is active, determined by requireConfirmation property of invite action and accept/reject actions.


disabled boolean readonly
If access is disabled, determined by enable/disable actions.


rejected boolean readonly
If invited user has rejected the invitation using accept/reject actions.


createdAt date readonly
When the instance was created.


updatedAt date readonly
When the instance was last updated.


Invite user to Organization

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/invite" \
  -H "Authorization: LAUNCH_CODE" \
  -d email="invited@spaceinvoices.com"

Returns:

{
  "id": "5e9ab369ed6377000d23d5b5",
  "accountId": "5a3683ea12d5a67dd0ef2f4d",
  "role": "default",
  "active": true,
  "rejected": false,
  "disabled": false
}

This endpoint allows adding users (Accounts) to Organizations, granting the user access rights to perform actions on the particular Organization.

It's not required for the invited user to have an Account prior to inviting them, when inviting with email the API will link the Account of the invited user when they sign up. In this case the invitation email will direct the user to sign up.

To silently add a user to an Organization simply set both requireConfirmation and sendEmail to false.
The added user can then be logged in or controled using the impersonate method.
Note that the Account must already exist otherwise one must be signed up.

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/invite

Route parameters

id string required
ID of the Organization being invited to


Properties

accountId string
ID of Account being invited.
Required if email not set.


role string
Role of Account, one of default, admin, readonly.
Currently the roles have more affect on actions in Apollo UI but will be expanded to more API actions as well.


email string
Email of Account being invited.
Required if accountId not set.


requireConfirmation boolean default true
If the invited user must confirm the invitation first to activate access.


sendEmail boolean default true
If an invitation/access granted email should be sent to the invited user's email.


List Accounts with access to Organization

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/accountorganizations" \
  -H "Authorization: LAUNCH_CODE"

Returns:

[{
  "id": "5e9ab369ed6377000d23d5b5",
  "accountId": "5a3683ea12d5a67dd0ef2f4d",
  "role": "default",
  "active": true,
  "rejected": false,
  "disabled": false
}, ...]

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/accountorganizations

Route parameters

id string required
ID of the Organization on which the Access is being listed


Remove Account from Organization

curl -X DELETE "https://api.spaceinvoices.com/v1/accountorganizations/5e9ab369ed6377000d23d5b5" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "success": true
}

Removes the user from the Organization revoking their access and rights.

HTTP Request

DELETE https://api.spaceinvoices.com/v1/accountorganizations/:id

Route parameters

id string required
ID of the Access being removed


Disable access to Organization

curl -X POST "https://api.spaceinvoices.com/v1/accountorganizations/5e9ab369ed6377000d23d5b5/disable" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "success": true
}

Disables the access rights for a user without removing them from the Organization.

HTTP Request

POST https://api.spaceinvoices.com/v1/accountorganizations/:id/disable

Route parameters

id string required
ID of the Access being disabled


Enable access to Organization

curl -X POST "https://api.spaceinvoices.com/v1/accountorganizations/5e9ab369ed6377000d23d5b5/enable" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "success": true
}

Enables the access rights for a user with access to the Organization.

HTTP Request

POST https://api.spaceinvoices.com/v1/accountorganizations/:id/enable

Route parameters

id string required
ID of the Access being enabled


Change access role

curl "https://api.spaceinvoices.com/v1/accountorganizations/5e9ab369ed6377000d23d5b5/change-role" \
  -H "Authorization: LAUNCH_CODE" \
  -d role="default"

Returns:

{
  "success": true
}

HTTP Request

POST https://api.spaceinvoices.com/v1/accountorganizations/:id/change-role

Route parameters

id string required
ID of the Access being changed


Payments

Endpoints:

  POST /v1/documents/:id/payments
   GET /v1/payments/:id
 PATCH /v1/payments/:id
DELETE /v1/payments/:id
   GET /v1/organization/:id/payments
   GET /v1/organization/:id/payments/count
   GET /v1/documents/:id/payments
   GET /v1/documents/:id/payments/count

Payments are stored for each document. Each document can have multiple payments that can also sum up to more than the invoice's total value.
Payments are in the Currency of the document.

It's also possible to add payments in the same call as creating the document if it's already been paid at the time of creation, see the payments property in the create a Document section.

The Payment object

The Payment object:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "documentId": "5a3683ea12d5a67dd0ef2f4d",
  "organizationId": "5a3683ea12d5a67dd0ef2f4e",
  "type": "bank",
  "date": "2020-04-18",
  "amount": 1000
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z"
}

Properties

id string readonly
Unique identifier.


organizationId string readonly
ID reference to Organization the Payment belongs to.


documentId string readonly
ID reference to Document the Payment belongs to.


type
Type of payment, one of bank, online, paypal, cash, card, crypto, coupon, other.


date
Date of payment.


amount default document total due
Payment amount in document currency


description
Description of the Payment.


custom object
Custom data.
See Model custom data section for details.


createdAt date readonly
When the instance was created.


updatedAt date readonly
When the instance was last updated.


Create a Payment

curl "https://api.spaceinvoices.com/v1/documents/5a3683ea12d5a67dd0ef2f4d/payments" \
  -H "Authorization: LAUNCH_CODE" \
  -d type="bank" \
  -d date="2020-04-18" \
  -d amount=1000
spaceInvoices.payments
  .create(documentId, {
    type: "bank",
    date: "2020-04-18",
    amount: 1000,
  })
  .then(function (payment) {
    // Use the payment
  });
<?php
  Spaceinvoices\Payments::create("5a3683ea12d5a67dd0ef2f4d", array(
    "type" => "bank",
    "date" => "2020-04-18",
    "amount" => 1000
  ));
?>

Returns:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "documentId": "5a3683ea12d5a67dd0ef2f4d",
  "organizationId": "5a3683ea12d5a67dd0ef2f4e",
  "type": "bank",
  "date": "2020-04-18",
  "amount": 1000
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z"
}

HTTP Request

POST https://api.spaceinvoices.com/v1/organizations/:id/payments

Route parameters

id string required
ID of the Organization on which the Payment is being created


Properties

type required
Type of payment, one of bank, online, paypal, cash, card, crypto, coupon, other.


date required
Date of payment.


amount default document total due
Payment amount in document currency


description
Description of the Payment.


custom object
Custom data.
See Model custom data section for details.


Retrieve a Payment

curl "https://api.spaceinvoices.com/v1/payments/5a3683ea12d5a67dd0ef2f4c" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "documentId": "5a3683ea12d5a67dd0ef2f4d",
  "organizationId": "5a3683ea12d5a67dd0ef2f4e",
  "type": "bank",
  "date": "2020-04-18",
  "amount": 1000
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z"
}

HTTP Request

GET https://api.spaceinvoices.com/v1/payments/:id

Route parameters

id string required
ID of the Payment being retrieved


Update a Payment

curl -X PUT "https://api.spaceinvoices.com/v1/payments/5a3683ea12d5a67dd0ef2f4c" \
  -H "Authorization: LAUNCH_CODE" \
  -d type="bank" \
  -d documentId="5a3683ea12d5a67dd0ef2f4d" \
  -d date="2020-04-18" \
  -d amount=1000
spaceInvoices.payments
  .edit(paymentId, {
    type: "bank",
    documentId: documentId,
    date: "2020-04-18",
    amount: 1000,
  })
  .then(function (payment) {
    // Use the payment
  });
<?php
  Spaceinvoices\Payments::edit("5a3683ea12d5a67dd0ef2f4c", array(
    "type" => "bank",
    "documentId" => "DOCUMENT_ID"
    "date" => "2020-04-18",
    "amount" => 1000,
  ));
?>

Returns:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "documentId": "5a3683ea12d5a67dd0ef2f4d",
  "organizationId": "5a3683ea12d5a67dd0ef2f4e",
  "type": "bank",
  "date": "2020-04-18",
  "amount": 1000
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z"
}

Unlike other models, the Item model performs a full replace when updating instead of a partial update requiring the full item data to be posted when updating.

HTTP Request

PUT https://api.spaceinvoices.com/v1/payments/:id

Route parameters

id string required
ID of the Payment being updated


Properties

type
Type of payment, one of bank, online, paypal, cash, card, crypto, coupon, other.


date
Date of payment.


amount default document total due
Payment amount in document currency


description
Description of the Payment.


custom object
Custom data.
See Model custom data section for details.


Delete a Payment

curl -X DELETE "https://api.spaceinvoices.com/v1/payments/5a3683ea12d5a67dd0ef2f4c" \
  -H "Authorization: LAUNCH_CODE"
spaceInvoices.payments
  .delete("5a3683ea12d5a67dd0ef2f4c")
  .then(function (count) {
    // Delete count
  });
<?php
  Spaceinvoices\Payments::delete("5a3683ea12d5a67dd0ef2f4c");
?>

Returns:

{
  "count": 1
}

HTTP Request

DELETE https://api.spaceinvoices.com/v1/payments/:id

Route parameters

id string required
ID of the Payment being deleted


List all Payments

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/payments" \
  -H "Authorization: LAUNCH_CODE"
spaceInvoices.payments.list("ORG_ID").then(function (payments) {
  // Use the payments
});
<?php
  Spaceinvoices\Payments::find("ORG_ID");
?>

Returns:

[{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "documentId": "5a3683ea12d5a67dd0ef2f4d",
  "organizationId": "5a3683ea12d5a67dd0ef2f4e",
  "type": "bank",
  "date": "2020-04-18",
  "amount": 1000
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z"
}, ...]

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/payments

Route parameters

id string required
ID of the Organization on which the payments are being listed


filter object
Query filters. See Filters section for more details.


Count all Payments

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/payments/count" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "count": 1
}

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/payments/count

Route parameters

id string required
ID of the Organization on which the payments are being counted


where object
Query where. See Where operators section of filters for more details.


List all Document's Payments

curl "https://api.spaceinvoices.com/v1/documents/5a3683ea12d5a67dd0ef2f4d/payments" \
  -H "Authorization: LAUNCH_CODE"
spaceInvoices.payments
  .listDocumentPayments("5a3683ea12d5a67dd0ef2f4d")
  .then(function (payments) {
    // Use the payments
  });
<?php
  Spaceinvoices\Payments::findDocumentPayments("5a3683ea12d5a67dd0ef2f4d");
?>

Payment can also be included when retrieving Documents, see filters section for more details.

Returns:

[{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "documentId": "5a3683ea12d5a67dd0ef2f4d",
  "organizationId": "5a3683ea12d5a67dd0ef2f4e",
  "type": "bank",
  "date": "2020-04-18",
  "amount": 1000
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z"
}, ...]

HTTP Request

GET https://api.spaceinvoices.com/v1/documents/:id/payments

Route parameters

id string required
ID of the Document on which the payments are being listed


filter object
Query filters. See Filters section for more details.


Count all Document's Payments

curl "https://api.spaceinvoices.com/v1/documents/5a3683ea12d5a67dd0ef2f4d/payments/count" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "count": 1
}

HTTP Request

GET https://api.spaceinvoices.com/v1/documents/:id/payments/count

Route parameters

id string required
ID of the Document on which the payments are being counted


where object
Query where. See Where operators section of filters for more details.


Recurrences

Endpoints:

  POST /v1/documents/:id/recurrences
   GET /v1/recurrences/:id
 PATCH /v1/recurrences/:id
DELETE /v1/recurrences/:id
   GET /v1/documents/:id/recurrences
   GET /v1/organizations/:id/recurrences
   GET /v1/organizations/:id/recurrences/count

Recurrences are created for Documents. A recurrence dictates when a periodic automatic creation of a document occurs using the original document content as a base while changing the document's dates and number.

Recurrences are great for repetative business or subscriptions.

The Recurrence object

The Recurrence object:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "documentId": "5a3683ea12d5a67dd0ef2f4d",
  "organizationId": "5a3683ea12d5a67dd0ef2f4e",
  "accountId": "5a3683ea12d5a67dd0ef2f4f",
  "name": "Monthly recurrence",
  "type": "month",
  "dateFirst": "2018-01-01",
  "numRecurrences": 2,
  "autoSend": false,
  "notify": true,
  "saveAsDraft": false,
  "_recurrenceDates": [
    {
      "date": "2020-02-01",
      "iteration": 1
    }, {
      "date": "2020-03-01",
      "iteration": 2
    }
  ]
  "custom": {},
  "createdAt": "2020-01-18T07:59:37.938Z",
  "updatedAt": "2020-01-18T07:59:37.938Z"
}

Properties

id string readonly
Unique identifier.


organizationId string readonly
ID reference to Organization the Client belongs to.


accountId string readonly
ID reference to Account that created the Client.


documentId string readonly
ID reference to Document the Payment belongs to.


name string
Name of the recurrence.


type string required
Type of the recurrence, one of week / month / year. |


dateFirst date required
Date of the first recurrence.


numRecurrences number required
Number of the Recurrence.


autoSend boolean default false
If a created Document should be automatically sent to Client's email when created. Requires that Client has email set, either the one in the _documentClient or the one linked with clientId.


notify boolean default true
If the Account that created the Recurrence should be notified when a Document is created


saveAsDraft boolean default false
If the invoice should be created as draft.


recurrenceDates array
Collection of objects containing created Recurrence dates.

toggle child attributes


date date
Date of the Recurrence.


iteration number
Iteration index of the Recurrence.


custom object
Custom data.
See Model custom data section for details.


createdAt date readonly
When the instance was created.


updatedAt date readonly
When the instance was last updated.


Create New Recurrence

curl "https://api.spaceinvoices.com/v1/documents/5a3683ea12d5a67dd0ef2f4d/recurrence" \
  -H "Authorization: LAUNCH_CODE" \
  -d name="Monthly recurrence" \
  -d type="month" \
  -d dateFirst="2020-02-01" \
  -d numRecurrences=2
spaceInvoices.recurrences
  .create("5a3683ea12d5a67dd0ef2f4d", {
    name: "Monthly recurrence",
    type: "month",
    dateFirst: "2020-02-01",
    numRecurrences: 2,
  })
  .then(function (recurrence) {
    // Use the recurrence
  });
<?php
  Spaceinvoices\Recurrences::create("5a3683ea12d5a67dd0ef2f4d", array(
    "name" => "Monthly recurrence",
    "type" => "month",
    "dateFirst" => "2020-02-01",
    "numRecurrences" => 2
  ));
?>

Returns:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "documentId": "5a3683ea12d5a67dd0ef2f4d",
  "organizationId": "5a3683ea12d5a67dd0ef2f4e",
  "accountId": "5a3683ea12d5a67dd0ef2f4f",
  "name": "Monthly recurrence",
  "type": "month",
  "dateFirst": "2018-01-01",
  "numRecurrences": 2,
  "autoSend": false,
  "notify": true,
  "saveAsDraft": false,
  "_recurrenceDates": [
    {
      "date": "2020-02-01",
      "iteration": 1
    }, {
      "date": "2020-03-01",
      "iteration": 2
    }
  ]
  "custom": {},
  "createdAt": "2020-01-18T07:59:37.938Z",
  "updatedAt": "2020-01-18T07:59:37.938Z"
}

HTTP Request

POST https://api.spaceinvoices.com/v1/documents/:id/recurrences

Route parameters

id string required
ID of the Document on which the Recurrence is being created


Properties

name string required
Name of the recurrence.


type string required
Type of the recurrence, one of week / month / year. |


dateFirst date required
Date of the first recurrence.


numRecurrences number required
Number of the Recurrence.


autoSend boolean default false
If a created Document should be automatically sent to Client's email when created. Requires that Client has email set, either the one in the _documentClient or the one linked with clientId.


notify boolean default true
If the Account that created the Recurrence should be notified when a Document is created


saveAsDraft boolean default false
If the invoice should be created as draft.


Retrieve a Recurrence

curl "https://api.spaceinvoices.com/v1/recurrences/5a3683ea12d5a67dd0ef2f4c" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "documentId": "5a3683ea12d5a67dd0ef2f4d",
  "organizationId": "5a3683ea12d5a67dd0ef2f4e",
  "accountId": "5a3683ea12d5a67dd0ef2f4f",
  "name": "Monthly recurrence",
  "type": "month",
  "dateFirst": "2018-01-01",
  "numRecurrences": 2,
  "autoSend": false,
  "notify": true,
  "saveAsDraft": false,
  "_recurrenceDates": [
    {
      "date": "2020-02-01",
      "iteration": 1
    }, {
      "date": "2020-03-01",
      "iteration": 2
    }
  ]
  "custom": {},
  "createdAt": "2020-01-18T07:59:37.938Z",
  "updatedAt": "2020-01-18T07:59:37.938Z"
}

HTTP Request

GET https://api.spaceinvoices.com/v1/recurrences/:id

Route parameters

id string required
ID of the Recurrence being retrieved


Update a Recurrence

curl "https://api.spaceinvoices.com/v1/recurrences/5a3683ea12d5a67dd0ef2f4c" \
  -H "Authorization: LAUNCH_CODE" \
  -d name="Monthly recurrence" \
  -d type="month" \
  -d dateFirst="2020-02-01" \
  -d numRecurrences=2

Returns:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "documentId": "5a3683ea12d5a67dd0ef2f4d",
  "organizationId": "5a3683ea12d5a67dd0ef2f4e",
  "accountId": "5a3683ea12d5a67dd0ef2f4f",
  "name": "Monthly recurrence",
  "type": "month",
  "dateFirst": "2018-01-01",
  "numRecurrences": 2,
  "autoSend": false,
  "notify": true,
  "saveAsDraft": false,
  "_recurrenceDates": [
    {
      "date": "2020-02-01",
      "iteration": 1
    }, {
      "date": "2020-03-01",
      "iteration": 2
    }
  ]
  "custom": {},
  "createdAt": "2020-01-18T07:59:37.938Z",
  "updatedAt": "2020-01-18T07:59:37.938Z"
}

Unlike other models, the Recurrence model performs a full replace when updating instead of a partial update requiring the full object data to be posted.

HTTP Request

PUT https://api.spaceinvoices.com/v1/recurrences/:id

Route parameters

id string required
ID of the Recurrence being updated


Properties

name string required
Name of the recurrence.


type string required
Type of the recurrence, one of week / month / year. |


dateFirst date required
Date of the first recurrence.


numRecurrences number required
Number of the Recurrence.


autoSend boolean default false
If a created Document should be automatically sent to Client's email when created. Requires that Client has email set, either the one in the _documentClient or the one linked with clientId.


notify boolean default true
If the Account that created the Recurrence should be notified when a Document is created


saveAsDraft boolean default false
If the invoice should be created as draft.


Delete Recurrence

curl -X DELETE "https://api.spaceinvoices.com/v1/recurrences/5a3683ea12d5a67dd0ef2f4c" \
  -H "Authorization: LAUNCH_CODE"
spaceInvoices.recurrences
  .delete("5a3683ea12d5a67dd0ef2f4c")
  .then(function (count) {
    // Deleted count
  });
<?php
  Spaceinvoices\Recurrences::delete("5a3683ea12d5a67dd0ef2f4c");
?>

Returns:

{
  "count": 1
}

HTTP Request

DELETE https://api.spaceinvoices.com/v1/recurrences/:id

Route parameters

id string required
ID of the Recurrence being deleted


List all Document's Recurrences

curl "https://api.spaceinvoices.com/v1/documents/5a3683ea12d5a67dd0ef2f4d/recurrence" \
  -H "Authorization: LAUNCH_CODE"
spaceInvoices.recurrences
  .listDocumentRecurrences("5a3683ea12d5a67dd0ef2f4d")
  .then(function (recurrences) {
    // Use the recurrences
  });
<?php
  Spaceinvoices\Recurrences::findDocumentRecurrences("5a3683ea12d5a67dd0ef2f4d");
?>

Recurrence can also be included when retrieving Documents, see filters section for more details.

Returns:

[{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "documentId": "5a3683ea12d5a67dd0ef2f4d",
  "organizationId": "5a3683ea12d5a67dd0ef2f4e",
  "accountId": "5a3683ea12d5a67dd0ef2f4f",
  "name": "Monthly recurrence",
  "type": "month",
  "dateFirst": "2018-01-01",
  "numRecurrences": 2,
  "autoSend": false,
  "notify": true,
  "saveAsDraft": false,
  "_recurrenceDates": [
    {
      "date": "2020-02-01",
      "iteration": 1
    }, {
      "date": "2020-03-01",
      "iteration": 2
    }
  ]
  "custom": {},
  "createdAt": "2020-01-18T07:59:37.938Z",
  "updatedAt": "2020-01-18T07:59:37.938Z"
}, ...]

HTTP Request

GET https://api.spaceinvoices.com/v1/documents/:id/recurrences

Route parameters

id string required
ID of the Document on which the recurrences are being listed


filter object
Query filters. See Filters section for more details.


List all Recurrences

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/recurrences" \
  -H "Authorization: LAUNCH_CODE"
spaceInvoices.recurrences.list("ORG_ID").then(function (recurrences) {
  // Use the recurrences
});
<?php
  Spaceinvoices\Recurrences::find("ORG_ID");
?>

Returns:

[{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "documentId": "5a3683ea12d5a67dd0ef2f4d",
  "organizationId": "5a3683ea12d5a67dd0ef2f4e",
  "accountId": "5a3683ea12d5a67dd0ef2f4f",
  "name": "Monthly recurrence",
  "type": "month",
  "dateFirst": "2018-01-01",
  "numRecurrences": 2,
  "autoSend": false,
  "notify": true,
  "saveAsDraft": false,
  "_recurrenceDates": [
    {
      "date": "2020-02-01",
      "iteration": 1
    }, {
      "date": "2020-03-01",
      "iteration": 2
    }
  ]
  "custom": {},
  "createdAt": "2020-01-18T07:59:37.938Z",
  "updatedAt": "2020-01-18T07:59:37.938Z"
}, ...]

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/recurrences

Route parameters

id string required
ID of the Organization on which the recurrences are being listed


filter object
Query filters. See Filters section for more details.


Count all Recurrences

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/recurrences/count" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "count": 1
}

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/recurrences/count

Route parameters

id string required
ID of the Organization on which the recurrences are being counted


where object
Query where. See Where operators section of filters for more details.


Taxes

Endpoints:

  POST /v1/organizations/:id/taxes
   GET /v1/taxes/:id
   PUT /v1/taxes/:id
DELETE /v1/taxes/:id
   GET /v1/organizations/:id/taxes
   GET /v1/organizations/:id/taxes/count
  POST /v1/taxes/:id/taxrates
DELETE /v1/taxes/:id/taxrates/:id

Taxes are stored per Organization and are then referenced on Items for which tax is chargeable.

Each tax may have different rates applied to them, and the rates may be set for a specific date range for which the rate is in effect. The actual tax rate charged for any given item are chosen based on the document's indicated date if specific rates are applicable on the date of invoice issue. This ensures the correct tax rates are applied to documents.

NOTE: When adding taxes to document items or items, the tax can be easily referenced (in prioritized order) by its id, rate, or classification.

The Tax object

The Tax object:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "organizationId": "5a3683ea12d5a67dd0ef2f4d",
  "name": "Goods and Services Tax",
  "abbreviation": "GST",
  "classification": "standard",
  "_taxRates": [
    {
      "id": "03572004-45f5-42d5-a4bb-90dc66f8f842",
      "rate": 15,
      "dateValidFrom": "1970-01-01",
      "custom": {},
      "createdAt": "2020-04-18T07:59:37.938Z",
      "updatedAt": "2020-04-18T07:59:37.938Z",
    }
  ],
  "recoverable": true,
  "compound": false,
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z",
}

Properties

id string readonly
Unique identifier.


organizationId string readonly
ID reference to Organization the Item belongs to.


name string


abbreviation string
Abbreviation of tax, used for display.


classification string
Tax classification.
If provided and rate not provided, the API attempts to match tax by it from the database and populate it.


_taxRates array
Collection of rates the Tax has.
Is automatically sorted by dateValidFrom of validity, most recent first.

toggle child attributes


rate number
% rate of the tax.


dateValidFrom date default epoch
When the rate came into force.
Used on Documents to determine which rate should be used based on Document date.


recoverable boolean
If the tax is recoverable.


reverseCharged boolean
If the tax is reverse (self) charged.
Reverse charged tax is not applied to totals and is added to the Document's reverse taxes.


compound boolean
If tax is compound.
Compound tax is calculated on top of the total with tax sum after other taxes that are applied to the Item.


custom object
Custom data.
See Model custom data section for details.


createdAt date readonly
When the instance was created.


updatedAt date readonly
When the instance was last updated.


Create a Tax

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/taxes" \
  -H "Authorization: LAUNCH_CODE" \
  -d name="Goods and Services Tax" \
  -d abbreviation="GST" \
  -d classification="standard" \
  -d _taxRates[0][rate]=15
spaceInvoices.taxes
  .create(organizationId, {
    name: "Goods and Services Tax",
    abbreviation: "GST",
    classification: "standard",
    _taxRates: [
      {
        rate: 15,
      },
    ],
  })
  .then(function (tax) {
    // Use the tax
  });
<?php
  Spaceinvoices\Taxes::create("ORG_ID", array(
    "name" => "Goods and Services Tax",
    "abbreviation" => "GST",
    "classification": "standard",
    "_taxRates" => [array(
      "rate" => 15
    )]
  ));
?>

Returns:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "organizationId": "5a3683ea12d5a67dd0ef2f4d",
  "name": "Goods and Services Tax",
  "abbreviation": "GST",
  "classification": "standard",
  "_taxRates": [
    {
      "id": "03572004-45f5-42d5-a4bb-90dc66f8f842",
      "rate": 15,
      "dateValidFrom": "1970-01-01",
      "custom": {},
      "createdAt": "2020-04-18T07:59:37.938Z",
      "updatedAt": "2020-04-18T07:59:37.938Z",
    }
  ],
  "recoverable": true,
  "compound": false,
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z",
}

HTTP Request

POST https://api.spaceinvoices.com/v1/organizations/:id/taxes

Route parameters

id string required
ID of the Organization on which the Tax is being created


Properties

name string required


abbreviation string
Abbreviation of tax, used for display.


classification string
Tax classification.
If provided and rate not provided, the API attempts to match tax by it from the database and populate it.


_taxRates array required
Collection of rates the Tax has.
Is automatically sorted by dateValidFrom of validity, most recent first.

toggle child attributes


rate number required
% rate of the tax.


dateValidFrom date default epoch
When the rate came into force.
Used on Documents to determine which rate should be used based on Document date.


recoverable boolean
If the tax is recoverable.


reverseCharged boolean
If the tax is reverse (self) charged.
Reverse charged tax is not applied to totals and is added to the Document's reverse taxes.


compound boolean
If tax is compound.
Compound tax is calculated on top of the total with tax sum after other taxes that are applied to the Item.


custom object
Custom data.
See Model custom data section for details.


Retrieve a Tax

curl "https://api.spaceinvoices.com/v1/taxes/5a3683ea12d5a67dd0ef2f4c" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "organizationId": "5a3683ea12d5a67dd0ef2f4d",
  "name": "Goods and Services Tax",
  "abbreviation": "GST",
  "classification": "standard",
  "_taxRates": [
    {
      "id": "03572004-45f5-42d5-a4bb-90dc66f8f842",
      "rate": 15,
      "dateValidFrom": "1970-01-01",
      "custom": {},
      "createdAt": "2020-04-18T07:59:37.938Z",
      "updatedAt": "2020-04-18T07:59:37.938Z",
    }
  ],
  "recoverable": true,
  "compound": false,
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z",
}

HTTP Request

GET https://api.spaceinvoices.com/v1/taxes/:id

Route parameters

id string required
ID of the Tax being retrieved


Update a Tax

curl -X PUT "https://api.spaceinvoices.com/v1/taxes/5a3683ea12d5a67dd0ef2f4c" \
  -H "Authorization: LAUNCH_CODE" \
  -d name="Goods and Services Tax" \
  -d abbreviation="GST" \
  -d classification="standard" \
  -d _taxRates[0][rate]=15
spaceInvoices.taxes
  .edit("5a3683ea12d5a67dd0ef2f4c", {
    name: "Goods and Services Tax",
    abbreviation: "GST",
    classification: "standard",
    _taxRates: [
      {
        rate: 15,
      },
    ],
  })
  .then(function (tax) {
    // Use the tax
  });
<?php
  Spaceinvoices\Taxes::edit("5a3683ea12d5a67dd0ef2f4c", array(
    "name" => "Goods and Services Tax",
    "abbreviation" => "GST",
    "classification": "standard",
    "_taxRates" => [array(
      "rate" => 15
    )]
  ));
?>

Returns:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "organizationId": "5a3683ea12d5a67dd0ef2f4d",
  "name": "Goods and Services Tax",
  "abbreviation": "GST",
  "classification": "standard",
  "_taxRates": [
    {
      "id": "03572004-45f5-42d5-a4bb-90dc66f8f842",
      "rate": 15,
      "dateValidFrom": "1970-01-01",
      "custom": {},
      "createdAt": "2020-04-18T07:59:37.938Z",
      "updatedAt": "2020-04-18T07:59:37.938Z",
    }
  ],
  "recoverable": true,
  "compound": false,
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z",
}

Unlike other models, the Tax model performs a full replace when updating instead of a partial update requiring the full object data to be posted.

HTTP Request

PUT https://api.spaceinvoices.com/v1/taxes/:id

Route parameters

id string required
ID of the Tax being updated


Properties

name string required


abbreviation string
Abbreviation of tax, used for display.


classification string
Tax classification.
If provided and rate not provided, the API attempts to match tax by it from the database and populate it.


_taxRates array required
Collection of rates the Tax has.
Is automatically sorted by dateValidFrom of validity, most recent first.

toggle child attributes


rate number required
% rate of the tax.


dateValidFrom date default epoch
When the rate came into force.
Used on Documents to determine which rate should be used based on Document date.


recoverable boolean
If the tax is recoverable.


reverseCharged boolean
If the tax is reverse (self) charged.
Reverse charged tax is not applied to totals and is added to the Document's reverse taxes.


compound boolean
If tax is compound.
Compound tax is calculated on top of the total with tax sum after other taxes that are applied to the Item.


custom object
Custom data.
See Model custom data section for details.


Delete a Tax

curl -X DELETE "https://api.spaceinvoices.com/v1/taxes/5a3683ea12d5a67dd0ef2f4c" \
  -H "Authorization: LAUNCH_CODE"
spaceInvoices.taxes.delete("5a3683ea12d5a67dd0ef2f4c").then(function (count) {
  // Deleted count
});
<?php
  Spaceinvoices\Taxes::delete("5a3683ea12d5a67dd0ef2f4c");
?>

Returns:

{
  "count": 1
}

A Tax can only be deleted if it is not used on any Document.

HTTP Request

DELETE https://api.spaceinvoices.com/v1/taxes/:id

Route parameters

id string required
ID of the Tax being deleted


List all Taxes

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/taxes" \
  -H "Authorization: LAUNCH_CODE"
spaceInvoices.taxes.list("ORG_ID").then(function (taxes) {
  // Use the taxes
});
<?php
  Spaceinvoices\Taxes::find("ORG_ID");
?>

Returns:

[{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "organizationId": "5a3683ea12d5a67dd0ef2f4d",
  "name": "Goods and Services Tax",
  "abbreviation": "GST",
  "classification": "standard",
  "_taxRates": [
    {
      "id": "03572004-45f5-42d5-a4bb-90dc66f8f842",
      "rate": 15,
      "dateValidFrom": "1970-01-01",
      "custom": {},
      "createdAt": "2020-04-18T07:59:37.938Z",
      "updatedAt": "2020-04-18T07:59:37.938Z",
    }
  ],
  "recoverable": true,
  "compound": false,
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z",
}, ...]

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/taxes

Route parameters

id string required
ID of the Organization on which the taxes are being listed


filter object
Query filters. See Filters section for more details.


Add a Rate to a Tax

curl "https://api.spaceinvoices.com/v1/taxes/5a3683ea12d5a67dd0ef2f4c/taxRates" \
  -H "Authorization: LAUNCH_CODE" \
  -d rate=20 \
  -d dateValidFrom="2018-01-01"
spaceInvoices.taxes
  .addANewRateToTax(taxId, {
    rate: 20,
    dateValidFrom: "2018-01-01",
  })
  .then(function (tax) {
    // Use the tax rate
  });
<?php
  Spaceinvoices\Taxes::addANewRateToTax("5a3683ea12d5a67dd0ef2f4c", array(
    "rate" => 20,
    "dateValidFrom" => "2018-01-01"
  ));
?>

Returns:

{
  "id": "03572004-45f5-42d5-a4bb-90dc66f8f842",
  "rate": 15,
  "dateValidFrom": "1970-01-01",
  "custom": {},
  "createdAt": "2020-04-18T07:59:37.938Z",
  "updatedAt": "2020-04-18T07:59:37.938Z",
}

HTTP Request

GET https://api.spaceinvoices.com/v1/taxes/:id/taxrates

Route parameters

id string required
ID of the Tax on which the Rate is being added


Properties

rate number required
% rate of the tax.


dateValidFrom date default epoch
When the rate came into force.
Used on Documents to determine which rate should be used based on Document date.


custom object
Custom data.
See Model custom data section for details.


Delete a Rate from a Tax

curl -X DELETE "https://api.spaceinvoices.com/v1/taxes/5a3683ea12d5a67dd0ef2f4c/taxRates/:id" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "count": 1
}

HTTP Request

GET https://api.spaceinvoices.com/v1/taxes/:id/taxrates

Route parameters

id string required
ID of the Tax on which the Rate is being deleted


Other resources

Additional helper resources.

Companies

Endpoints:

GET /v1/companies
GET /v1/companies/search

Companies is a special read-only searchable collection of companies from public directories. If looking for an endpont to add user companies please refer to the Organizations section.

This data model is recommended for user interfaces as a "search while you type feature", allowing you to limit searches to specific countries based on the origin of the user.

We update this database as frequently as possible to ensure most recent data.

Current data coverage:

Have a country you would like to add to this list? Please do email us and we are happy to look into it.

The Company object

The Company object:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "name": "Space Exploration Technologies corp",
  "address": "Rocket Road",
  "city": "Hawthorne",
  "zip": "CA 90250",
  "country": "USA",
  "taxNumber": "",
  "taxSubject": true,
  "companyNumber": "123456789"
}

Properties

id string
Unique identifier.


name string
Name of the Company.


address string


address2 string


city string


zip string
ZIP / post code.


country string


taxNumber string
Tax number.


taxSubject boolean
If the Company is subject to VAT / GST / sales tax or other tax.


companyNumber string
Registration or similar number.


List all Companies

curl "https://api.spaceinvoices.com/v1/companies" \
  -H "Authorization: LAUNCH_CODE"
spaceInvoices.companies.list().then(function (companies) {
  console.log(companies);
});
<?php
  Spaceinvoices\Companies::find();
?>

Returns:

[{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "name": "Space Exploration Technologies corp",
  "address": "Rocket Road",
  "city": "Hawthorne",
  "zip": "CA 90250",
  "country": "USA",
  "taxNumber": "",
  "taxSubject": true,
  "companyNumber": "123456789"
}, ...]

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/companys

Route parameters

id string required
ID of the Organization on which the Company is being listed


filter object
Query filters. See Filters section for more details.


Search all Companies

curl "https://api.spaceinvoices.com/v1/companies/search?term=Space" \
  -H "Authorization: LAUNCH_CODE"
spaceInvoices.companies.search("space").then(function (companies) {
  // Use the companies
});
<?php
  Spaceinvoices\Companies::search('Space');
?>

Returns:

[{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "name": "Space Exploration Technologies corp",
  "address": "Rocket Road",
  "city": "Hawthorne",
  "zip": "CA 90250",
  "country": "USA",
  "taxNumber": "",
  "taxSubject": true,
  "companyNumber": "123456789"
}, ...]

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/companys?term=:term

Route parameters

id string required
ID of the Organization on which the Company is being searched


term string required
Term to search for.


Countries

Endpoints:

GET /v1/countries

List of 250 countries for which informational queries can be conducted (ie. english name, native name, currency, taxes, etc.)

While all the countries are present in the list, data about local taxes and currencies for some less common countries may not be available. We continually update the collection with country information as it is used to perform matching for companies created through our API.
We are always open for suggestions on how we can make this feature better! Please get in contact with us.

The Country object

The Country object:

[
  {
    "name": "United Kingdom of Great Britain and Northern Ireland",
    "alpha2Code": "GB",
    "alpha3Code": "GBR",
    "nativeName": "United Kingdom",
    "numericCode": "826",
    "translations": {
      "br": "Reino Unido",
      "pt": "Reino Unido",
      "nl": "Verenigd Koninkrijk",
      "hr": "Ujedinjeno Kraljevstvo",
      "fa": "بریتانیای کبیر و ایرلند شمالی",
      "de": "Vereinigtes Königreich",
      "es": "Reino Unido",
      "fr": "Royaume-Uni",
      "ja": "イギリス",
      "it": "Regno Unito"
    },
    "taxes": [
      {
        "name": "Value Added Tax",
        "abbreviation": "VAT",
        "rate": "20",
        "classification": "standard"
      },
      {
        "name": "Value Added Tax",
        "abbreviation": "VAT",
        "rate": "5",
        "classification": "reduced"
      },
      {
        "name": "Value Added Tax",
        "abbreviation": "VAT",
        "rate": "0",
        "classification": "additional"
      }
    ],
    "currency": "GBP"
  },
]

name string
Unique English name of the country.


alpha2Code string
Unique ISO 2 letter code of the country.


alpha3Code string
Unique ISO 3 letter code of the country.


nativeName string
Unique native name of the country.


numericCode string
Unique numeric code of the country.


translations object
Names of the country translated to other languages.

toggle child attributes

key string
Alpha2Code of the country the name is translated to.


value string
The translated name of country.


taxes array
Object of country taxes and rates.
Usually value added tax. Tax data for least-used countries are not available at the moment.

toggle child attributes


name string
Name of the tax.


abbreviation string
Abbreviation of the tax.


rate string
Rate of the tax.


classification string
Classification of the tax rate ie. standard, reduced, additional in EU, state, federal, additional in US etc.


currency string
ISO 4217 name of currency primarily used in country.

List all Countries

curl "https://api.spaceinvoices.com/v1/countries" \
  -H "Authorization: LAUNCH_CODE"
spaceInvoices.countries.list().then((countries) => {
  // Use countries
});
<?php
  Spaceinvoices\Countries::find();
?>

Returns:

[
  {
    "name": "United Kingdom of Great Britain and Northern Ireland",
    "alpha2Code": "GB",
    "alpha3Code": "GBR",
    "nativeName": "United Kingdom",
    "numericCode": "826",
    "translations": {
      "br": "Reino Unido",
      "pt": "Reino Unido",
      "nl": "Verenigd Koninkrijk",
      "hr": "Ujedinjeno Kraljevstvo",
      "fa": "بریتانیای کبیر و ایرلند شمالی",
      "de": "Vereinigtes Königreich",
      "es": "Reino Unido",
      "fr": "Royaume-Uni",
      "ja": "イギリス",
      "it": "Regno Unito"
    },
    "taxes": [
      {
        "name": "Value Added Tax",
        "abbreviation": "VAT",
        "rate": "20",
        "classification": "standard"
      },
      {
        "name": "Value Added Tax",
        "abbreviation": "VAT",
        "rate": "5",
        "classification": "reduced"
      },
      {
        "name": "Value Added Tax",
        "abbreviation": "VAT",
        "rate": "0",
        "classification": "additional"
      }
    ],
    "currency": "GBP"
  },
  {
    "name": "Netherlands",
    "alpha2Code": "NL",
    "alpha3Code": "NLD",
    "nativeName": "Nederland",
    "numericCode": "528",
    "translations": {
      "br": "Holanda",
      "pt": "Países Baixos",
      "nl": "Nederland",
      "hr": "Nizozemska",
      "fa": "پادشاهی هلند",
      "de": "Niederlande",
      "es": "Países Bajos",
      "fr": "Pays-Bas",
      "ja": "オランダ",
      "it": "Paesi Bassi"
    },
    "taxes": [
      {
        "name": "Belasting toegevoegde waarde",
        "abbreviation": "BTW",
        "rate": "21",
        "classification": "standard"
      },
      {
        "name": "Belasting toegevoegde waarde",
        "abbreviation": "BTW",
        "rate": "6",
        "classification": "reduced"
      },
      {
        "name": "Belasting toegevoegde waarde",
        "abbreviation": "BTW",
        "rate": "0",
        "classification": "additional"
      }
    ],
    "currency": "EUR"
  },
  {
    "name": "Slovenia",
    "alpha2Code": "SI",
    "alpha3Code": "SVN",
    "nativeName": "Slovenija",
    "numericCode": "705",
    "translations": {
      "br": "Eslovênia",
      "pt": "Eslovénia",
      "nl": "Slovenië",
      "hr": "Slovenija",
      "fa": "اسلوونی",
      "de": "Slowenien",
      "es": "Eslovenia",
      "fr": "Slovénie",
      "ja": "スロベニア",
      "it": "Slovenia"
    },
    "taxes": [
      {
        "name": "Davek na dodano vrednost",
        "abbreviation": "DDV",
        "rate": "22",
        "classification": "standard"
      },
      {
        "name": "Davek na dodano vrednost",
        "abbreviation": "DDV",
        "rate": "9.5",
        "classification": "reduced"
      }
    ],
    "currency": "EUR"
  },
  ...
]

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/countrys

Route parameters

id string required
ID of the Organization on which the Country is being listed


filter object
Query filters. See Filters section for more details.


Currencies

Endpoints:

GET /v1/currencies

We current provide support for 122 of the most common global currencies. If there is one you'd like to use but do not see in the list, please write us.

In addition to normal (fiat) currencies, we have now also added some common cryptocurrencies. Don't see your favourite cryptocurrency as an option? Let us know and we'll be happy to add support for it.

Please note: ISO 4217 unique currency codes are used as the id fields of currencies to simplify inclusion in documents as related IDs.

The Currency object

The Currency object:

{
  "id": "EUR",
  "name": "European Union Euro",
  "symbol": "€",
  "type": "fiat"
}

Properties

isoName string
Unique ISO 4217 currency name.
Also used as unique ID of model instance.


name string
Name of the Currency.


symbol string
Symbol of the currency.


type string
Type of currency.
One of fiat or crypto


List all Currencies

curl "https://api.spaceinvoices.com/v1/currencies" \
  -H "Authorization: LAUNCH_CODE"
spaceInvoices.currency.list().then(function (currencies) {
  // Use the currencies
});
<?php
  Spaceinvoices\Currencies::find();
?>

HTTP Request

GET https://api.spaceinvoices.com/v1/currencies

Returns:

[{
  "id": "EUR",
  "name": "European Union Euro",
  "symbol": "€",
  "type": "fiat"
}, ...]

Webhooks

Endpoints:

  POST /v1/organizations/:id/webhooks
   GET /v1/webhooks/:id
 PATCH /v1/webhooks/:id
DELETE /v1/webhooks/:id
   GET /v1/organizations/:id/webhooks
   GET /v1/organizations/:id/webhooks/count

Webhooks allow subscribing to changes on most data models in Space Invoices.

When a Webhook subscription for a model event is triggered a POST request is sent to the registered URL.

If the request returns a 2** status the process is complete.

If a non 2** status is returned three additional re-tries will be made in 2 minutes, 4 minutes and finally in 8 minutes after the initial request.

The Webhook object

The Webhook object:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "organizationId": "5a3683ea12d5a67dd0ef2f4d",
  "events": [ "client/create" ]
}

Properties

id string readonly
Unique identifier.


organizationId string readonly
ID reference to Organization the Webhook belongs to.


url string
Url where information about the triggered Webhook event will be posted.


events array
Collection of events to subscribe to.
Each event must be of the format MODEL_NAME/EVENT_NAME.

enabled boolean
If Webhook is enabled.
Will not be triggered if not enabled.


createdAt date readonly
When the instance was created.


updatedAt date readonly
When the instance was last updated.


Create a Webhook

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/webhooks" \
  -H "Authorization: LAUNCH_CODE" \
  -d url="https://example.com" \
  -d events[0]="client/create"

Returns:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "organizationId": "5a3683ea12d5a67dd0ef2f4d",
  "events": [ "client/create" ]
}

HTTP Request

POST https://api.spaceinvoices.com/v1/organizations/:id/webhooks

Route parameters

id string required
ID of the Organization on which the Webhook is being created


Properties

url string required
Url where information about the triggered Webhook event will be posted.


events array required
Collection of events to subscribe to.
Each event must be of the format MODEL_NAME/EVENT_NAME.

enabled boolean
If Webhook is enabled.
Will not be triggered if not enabled.


Retrieve a Webhook

curl "https://api.spaceinvoices.com/v1/webhooks/5a3683ea12d5a67dd0ef2f4c" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "organizationId": "5a3683ea12d5a67dd0ef2f4d",
  "events": [ "client/create" ]
}

HTTP Request

GET https://api.spaceinvoices.com/v1/webhooks/:id

Route parameters

id string required
ID of the Webhook being retrieved


Update a Webhook

curl -X PATCH "https://api.spaceinvoices.com/v1/webhooks/5a3683ea12d5a67dd0ef2f4c" \
  -H "Authorization: LAUNCH_CODE"
  -d events[0]="client/create"

Returns:

{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "organizationId": "5a3683ea12d5a67dd0ef2f4d",
  "events": [ "client/create" ]
}

Updates the given model instance, any parameters not passed will be left untouched.

Properties

url string
Url where information about the triggered Webhook event will be posted.


events array
Collection of events to subscribe to.
Each event must be of the format MODEL_NAME/EVENT_NAME.

enabled boolean
If Webhook is enabled.
Will not be triggered if not enabled.


Delete a Webhook

curl -X DELETE "https://api.spaceinvoices.com/v1/webhooks/5a3683ea12d5a67dd0ef2f4c" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "count": 1
}

Performs a soft delete, see the Soft delete section for details.

HTTP Request

DELETE https://api.spaceinvoices.com/v1/webhooks/:id

Route parameters

id string required
ID of the Webhook being deleted


List all Webhooks

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/webhooks" \
  -H "Authorization: LAUNCH_CODE"

Returns:

[{
  "id": "5a3683ea12d5a67dd0ef2f4c",
  "organizationId": "5a3683ea12d5a67dd0ef2f4d",
  "events": [ "client/create" ]
}, ...]

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/webhooks

Route parameters

id string required
ID of the Organization on which the webhooks are being listed


filter object
Query filters. See Filters section for more details.


Count all Webhooks

curl "https://api.spaceinvoices.com/v1/organizations/ORG_ID/webhooks/count" \
  -H "Authorization: LAUNCH_CODE"

Returns:

{
  "count": 1
}

HTTP Request

GET https://api.spaceinvoices.com/v1/organizations/:id/webhooks/count

Route parameters

id string required
ID of the Organization on which the webhooks are being counted


where object
Query where. See Where operators section of filters for more details.


Supported model events

The following event types can be used when registering a Webhook subscription

create, update and delete

* - Indicates all subscriptions on all models, must be used without specifying a model.

Webhook event body

Posts:

{
  "event": "client/create",
  "organizationId": "",
  "data": {...},
  "uid": "859e2ee4-a1aa-45a1-b0d3-2dfe5b86a672"
}

Data posted to the registered URL endpoint when subscribed Webhook event is triggered

Properties

event string
Name of the triggered event.


organizationId string
The ID of the Organization on which the event was triggered.


data object
State data of model after the event.


uid
Unique identifier of the current triggered event request.


Apollo UI

https://app.getapollo.io

Apollo (app.getapollo.io) allows users to view data created through the API in a user friendly visual interface.

Each user with an account created through the API may login to Apollo with the same credentials in order to view the organizations for which they were allocated access permissions.

Apollo now supports White label and customization of styles to suit any brand. Get in touch with us for details.

https://app.getapollo.io

Fiscalization

Fiscalization is the process of reporting invoice fiscal data to tax authorities.

The feature is only available in the listed countries and is disabled by default until enabled by the users themselves.

Slovenia

We provide a complete mechanism for fiscalization based on Slovenian financial office's (Finančna Uprava Republike Slovenije - FURS) regulatory requirements.

It is required by law for all companies selling goods or services in Slovenia to report all cash or credit card paid invoices to govt. This also includes all invoices for which the form of payment is not known in advance. Additionally it is also required to fiscalize all advances and credit notes for previeously issued invoices that were fiscalized of will be fiscalized.

Fiscalization also requires additional data when creating documents, Space Invoice's validation changes when fiscalization is enabled to make sure appropriate data is provided.

WARNING: While we take great care to ensure fiscalization is performed as required by law and that our technical solution fits all requirements where applicable, we urge users to do their own research on the matter. Space Invoices can only ensure the technical aspect of the process, the final responsibility of fiscalization setup and operation is on the side of the user / provider of the data / the issuer of the invoices ie. the end user and not Space Invoices.

Setup

There is a setup involved before we can start taking advantage of this functionality.

HINT: Since this is usually a one time process we also provide a visual step-by-step tool (wizard if you will 🧙‍♂️) that can take you through the whole process of setting up all required configuration for fiscalization for a organization.

1. Certificate

To enable fiscalization one of the first steps is to acquire a certificate from the Slovenian Financial office (FURS), the certificate and passphrase can then be uploaded to Space Invoices and is required to register business premises and fiscalize invoices.

NOTE: A test certificate can be acquired from FURS and used with Space Invoices to create a test integration before going live. See the certificate section for more details.

2. Account configuration

First name, last name and tax number (if available) of the responsible person or person issuing the documents must be provided on the account that is creating documents.

For automatically generated documents it is recommended that users specify the company's responsible person ie. CEO's information. In case documents are issued manually then it is recommended to create an account for each person and adding their data.

Space Invoices will throw a validation error if this data is not provided. Please see the Account documentation for details.

A legal act must be created and stored by the issuing organization. Please see the Apollo interface for an example of one created based on the recommendations of FURS. The document is required by law and contains information about how documents are numbered.

To fully form this document a decision must be made about business premises and electronic devices, this step is a good point to do so.

Uploading the certificate and passphrase

curl "https://api.spaceinvoices.com/v1/organizations/:id/upload-certificate?type=furs" \
  -H "Authorization: LAUNCH_CODE" \
  -H "passphrase: CERTIFICATE_PASSWORD" \
  -F "certificate=@path/to/local/file"

If we perform multiple uploads the last certificate will be kept and the previous ones deleted.

The certificate's password is symmetrically encrypted with our own strong secret key and a per-password random generated unique strong key to ensure brute force protection and maximum security. Our key, the certificate and the password are all stored in separate locations with limited personel access.

NOTE: A test certificate can also be uploaded, take care to set the right (test) environment for the fiscalization configuration based on the type of uploaded certificate.

Adding business premisses

Business premieses must have unique identifier (name) set for businessPremiseId value.

The correct data for this is available and should be gathered from public records.

curl "https://api.spaceinvoices.com/v1/organizations/:id/businesspremises" \
  -H "Authorization: LAUNCH_CODE" \
  -d businessPremiseId="P1" \
  -d type="realestate" \

Adding electronic devices

An electronic device belongs to a business premise and must have a unique identifier (name) set for electronicDeviceId value. The value only has to be unique in the givven business premise the device is related to.

curl "https://api.spaceinvoices.com/v1/businesspremisses/:id/electronicdevices" \
  -H "Authorization: LAUNCH_CODE" \
  -d electronicDeviceId="D1" \

Going live / enabling fiscalization

Once all the above steps are complete we are ready to enable fiscalization.

NOTE: While we validate steps for fiscalization configuration, there are certain parts of the process, like the creation of the legal act, acquisition of a valid certificate, correct business premise and electronic device setup, that we do not control and is thus left to the users to ensure is correct before going live.

To enable fiscalization the following settings have to be added or updated on the given organization's defaults. See defaults section for more details.

furs_env String, defaults to production if not set and can also be test. Indicates which FURS fiscalization API endpoint to call.
furs_strategy String, defaults to C if not set, one of C, B. Indicates numbering strategy to use. Either per business premise (C) or per electronic device (B). C is the recommended value.
firs_verifying Boolean indicates if fiscalization is enabled.

Changelog

# 29.4.2020

# 16.4.2020

# 12.2.2019

# 4.11.2018

# 01.11.2018

# 24.10.2018

# 23.10.2018