Integrating user balances with external systems via the API

SimplyPrint's balance system can be controlled entirely through the API, letting you connect it to external billing platforms, webshops, or payment systems. This article explains when and why you'd want to do this, walks through common use cases, and points you to the right API endpoints.

Why integrate balances externally?

The balance system lets you assign each user a credit balance that gets deducted when they print. Instead of managing those balances manually inside SimplyPrint, you can use the API to keep them in sync with whatever system you already use for payments or accounting.

Some common scenarios:

• PaperCut or similar print management - Your organization already uses PaperCut to manage printing credits. You want 3D print costs in SimplyPrint to be reflected in PaperCut, or vice versa.
• Self-service webshop - You run a makerspace, fab lab, or print service and want users to purchase credits through your own website, which then tops up their SimplyPrint balance automatically.
• Accounting or ERP integration - Your finance team tracks printing costs in an external system and needs transaction data pushed there automatically.
• Custom kiosk or vending - You have a physical terminal where users tap a card or scan a code to add balance.

Getting started

You'll need an API key to make requests. Generate one from your account settings in SimplyPrint, and send it as a header: X-API-KEY: your-api-key-here

If you're building a product that will be used across multiple SimplyPrint accounts (not just your own), OAuth2 is also available. Reach out to us if this applies to you.

For full endpoint documentation, parameters, and response formats, see our API docs.

What you can do

The API gives you four main capabilities for balance management:

• Top up - Add funds to a user's balance. Use this when a user purchases credits in your external system.
• Adjust - Increase or decrease a user's balance by any amount. Use this for corrections, deductions, or syncing from another system.
• View history - Get a user's current balance and a paginated list of all past transactions, filterable by type.
• Check status - Get a snapshot of a user's balance and quota usage in one call.

Webhooks for real-time updates

Rather than polling the API to detect changes, you can subscribe to balance webhook events. Set these up in Settings > Webhooks and select the events you need.

Every balance webhook includes the full transaction details - amount, resulting balance, transaction type, reason, and timestamp.

Use case: PaperCut integration

Many schools and universities already use PaperCut to manage printing credits across regular paper printers. If you're adding SimplyPrint for 3D printers, you probably want a unified balance so students don't have to manage two separate systems.

Two-way sync flow:

1. A student starts a 3D print in SimplyPrint. The balance is deducted and a balance.charged webhook fires.
2. Your middleware receives the webhook and calls the PaperCut API to deduct the same amount.
3. Going the other way - when a student tops up in PaperCut, your middleware calls SimplyPrint's top-up endpoint to credit their SimplyPrint balance too.

SimplyPrint to PaperCut: Student prints in SimplyPrint → balance deducted → webhook fires → your server receives it → deducts in PaperCut

PaperCut to SimplyPrint: Student tops up in PaperCut → PaperCut notifies your server → your server tops up in SimplyPrint via API

Use case: webshop or payment portal

If you run a makerspace, library, or print service where users pay for 3D printing, you can let them purchase balance through your own website.

1. A user visits your webshop and pays for printing credits (via Stripe, PayPal, or however you handle payments).
2. After payment is confirmed, your backend calls the top-up endpoint with the purchased amount and a reference to the order.
3. The user's SimplyPrint balance is updated instantly and they can start printing.

You can also pull a user's transaction history via the API to show them their print charges and top-ups on your own site.

Use case: external billing or accounting

If your organization tracks costs in an ERP or accounting system, you can use webhooks to push all balance activity there automatically.

1. Subscribe to all four balance webhook events.
2. When any transaction occurs, your system receives the webhook with the full transaction details.
3. Map the data to your accounting entries. The transaction payload includes reference fields that link charges back to specific print jobs.

Tips

• Always include a reason. When topping up or adjusting via the API, include a descriptive reason. This shows up in the transaction history inside SimplyPrint and helps with auditing (e.g. "Webshop order #1234", "PaperCut sync").
• Use webhooks over polling. Webhooks fire in real time when something changes. Polling the API wastes requests and introduces delays.
• Handle refunds. When a print fails or is cancelled, SimplyPrint automatically refunds the user's balance. If you're syncing with an external system, listen for balance.refunded webhooks to keep both sides consistent.
• Use balance_after for reconciliation. Each transaction includes the resulting balance. If your external ledger disagrees, you know there's a sync gap to investigate.
• Check the API docs for full request/response details, rate limits, and error codes.

Updated on: 20/02/2026