npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

n8n-nodes-sphere

v0.1.0

Published

n8n community node for Sphere: real-time tax calculation, customers, products, transactions and transaction exports

Readme

n8n-nodes-sphere

This is an n8n community node for Sphere, the indirect tax platform for sales tax, VAT and GST. Use it to calculate tax in real time inside a billing or checkout workflow, record the finalized invoices and credit notes Sphere reports and files on, and export transactions with their tax breakdown as CSV.

n8n is a fair-code licensed workflow automation platform.

Installation · Credentials · Operations · Things to know · Development

Installation

Follow the installation guide in the n8n community nodes documentation and install n8n-nodes-sphere.

Credentials

Create an API key in Sphere under Settings > API Keys, or ask Sphere support for one. Keys start with sph_. Paste it into a Sphere API credential.

The credential test sends an empty tax calculation: Sphere answers a valid key with a validation error and an invalid one with unauthorized_access, so nothing is created. Customers, products and transactions need a key that Sphere has provisioned for the Transaction API; a key without it gets a 403 on those operations only.

Operations

| Resource | Operations | | --- | --- | | Tax | Calculate | | Transaction | Create or Update, Get, Cancel | | Customer | Create or Update, Get | | Product | Create or Update, Get | | Export | Create, Get, Cancel |

  • Tax > Calculate returns the tax per line and jurisdiction, a sphere_tax_calculation_id to store on the invoice or payment, and total_tax_amount, the tax summed over every line. Nothing is recorded.
  • Transaction > Create or Update records an invoice or credit note, as a pending draft or finalized. Finalizing runs the tax engine and returns subtotal, tax, total and an invoice link. Pass a sphere_tax_calculation_id to commit the exact tax quoted earlier instead of recalculating.
  • Export > Create starts a CSV export. Turn on Wait for Completion to poll until it is ready and Download File to attach the CSV as binary data.

Line items can be entered in the form or passed as a JSON array, which is how the lines of an invoice from an earlier node get mapped in.

Things to know

  • Two amount formats. Tax > Calculate takes whole numbers in the smallest currency unit (10000 is 100.00 EUR). Transactions take decimal strings in the main unit ("100.00"). The node labels each.
  • External IDs are the keys. Sphere has no list endpoints. Every record is created and fetched by the external_id you choose, and re-sending the same ID updates the record instead of creating a duplicate.
  • No tax is not an error. An empty tax_amounts means no tax is due: no registration for the location, an exempt customer or product, or a reverse charge. Turn on Include Taxability Reason to see which.
  • Products need a tax code. Tax > Calculate fails with invalid_product_tax_code for a product without one. Set it in Sphere's Products tab or with Product > Create or Update.
  • Rate limits. 10 writes and 50 reads per second per key; at most 3 exports running at once.

Compatibility

Built with @n8n/node-cli 0.54. Requires n8n 1.x or later with n8nNodesApiVersion 1.

Development

npm install
npm run dev        # runs n8n with the node linked, rebuilding on changes
npm run lint       # n8n community node rules
npm test           # description and helper tests
npm run build

The tests check every operation against Sphere's API reference: each URL and method must exist, and each body field the node sends, line item fields included, must be one the endpoint accepts. Sphere publishes the reference as OpenAPI fragments on each docs page; refresh the merged fixture with:

npm run sync:openapi

Resources

License

MIT