Your account
Tokens and billing
IwiConnect charges per project submitted to iwi. There is no subscription, no free trial, and no charge for drafts, users or reading anything.
What costs a token
A token is consumed when a project is submitted to iwi, whether that is PUT /projects/{id}/send or creating a project with draft: false. After that, an organisation's replies on the project cost a token every second reply.
Iwi accounts never spend tokens. Everything an iwi does through the API, including responding, completing and closing, is free.
| Action | Cost |
|---|---|
| Creating and editing a draft | Free |
| Submitting a project to iwi | One token |
| Responding as an organisation | Free or one token, alternating |
| Responding as an iwi | Free |
| Notes, documents, closing, completing, reopening | Free |
| Inviting users and managing groups | Free |
How the alternating reply works
A project carries a free reply from the moment it is sent. The organisation's first response uses it up and costs nothing. Their next response spends a token and restores the free reply, so the one after that is free again. In practice an organisation pays a token per round of kōrero rather than per message.
Because a response can spend a token, PUT /projects/{id}/respond can return 402 for an organisation with an empty balance, not just send.
Reopening a closed project does not charge again.
Checking the balance
GET /user carries current_credit_balance on each team. Check it before a batch run rather than discovering the shortfall halfway through.
{
"teams": [
{
"id": "3f1b0c77-9a5d-4d0b-8c3e-1f2a4b6c8d90",
"name": "Kāpiti Coast District Council",
"current_credit_balance": 12,
"role": "OWNER"
}
]
}
Running out
A send with no tokens returns 402.
{
"success": false,
"message": "No tokens available. Purchase tokens to submit this project.",
"status_code": 402,
"response_object": null
}
The project stays as a draft, fully intact. Nothing is lost, and the send will work once tokens are topped up. Treat a 402 as a queue-and-notify, not a failure to retry: retrying will 402 again until a human buys tokens.
A reasonable pattern is to alert when the balance drops below roughly a week of your normal volume, so purchasing happens before anyone is blocked.
Buying tokens
Tokens are bought in the portal through Stripe Checkout, by someone who can see the price and agree to it. Available quantities are 1, 5, 10, 20 and 50. The API will not charge a card on your behalf.
One exception. POST /projects accepts a quantity field, which returns a Stripe Checkout URL that a person then completes in a browser. The API still never takes payment by itself. It only opens the door.
Invoices and receipts
Stripe invoices for token purchases, newest first, paged. This is what finance wants.
Submission receipts, one per project sent, each with a receipt number, a submission number and a document_id you can turn into a PDF link through GET /download/{id}. This is what a consent authority wants.
The two are easy to confuse. An invoice proves you paid IwiConnect. A receipt proves you engaged with iwi on a specific project, and that is the one that ends up attached to an application.
Sandbox
Sandbox keys never consume tokens and never return 402, which is the point: you can exercise the full submission path as often as you like. It also means a sandbox run tells you nothing about whether production has the balance to do the same thing. Check the live balance separately before a first production batch.