Comparison to Calculations endpoint
Our endpoints are very similar to the Calculations endpoint, but they have a couple more fields:type (enum)
| Value | Description |
|---|---|
sale | represents a sale to your customers |
credit | represents a refund or credit memo issued to your customers. |
status (enum)
| Value | Description | Next states |
|---|---|---|
draft | transaction has not been issued yet, and is intended to be finalized soon (within 24 hours by default). The transaction’s line items can be edited. This will not be filed in this state. | finalized, void |
finalized | transaction has been issued and creates a tax liability (we will file it). The transaction’s line items are not intended to be edited. | filed, void |
filed | transaction has been filed | (terminal state) |
void | transaction has been effectively cancelled | (terminal state) |
parent_transaction_id (string, optional)
Represents the ID of the parent transaction in case of a credit memo/refund.
reference_id (string, optional)
Represents the ID of the transaction in an external billing system, like in Stripe you might have INV-123. These must be globally unique in your account.
tax_amount (decimal string, optional)
Represents the tax amount for the transaction. If not provided, we will calculate it and set it ourselves.
API endpoints
We have a small set of REST-style endpoints which can be used to create sale and credit transactions.| API endpoint | Description |
|---|---|
GET /transactions | list transactions (with filters). |
GET /transactions/{id} | retrieve a single transaction |
POST /transactions | create a transaction (sale or credit) |
POST /transactions/{id} | update a specific transaction |
Creating sale transactions
There are two ways of handling payments.Draft invoice method
A “draft” invoice is an invoice which will be finalized soon. This must be finalized within 24 hours.- Call our
POST /transactionsendpoint (with the same payload as thePOST /calculationscall), but also include a field"status": "draft". This will create a draft transaction in our system, and then return to you a transaction ID, and the tax due. - Create the actual invoice/payment in the billing system, with that tax amount.
- We recommend, but do not require, associating the Taxwire Transaction ID in the metadata of that billing system.
- When the external transaction is created, you can call our
POST /transactions/{id}field with{ "status": "finalized" }to signal that the sale has been completed. You also might want to also include"reference_id": <external_id>to the payload so it is easy to find the relevant Taxwire Transaction for that reference ID.
Calculation estimate method
Instead of creating a draft transaction and then finalizing it, you can also usePOST /calculations first to get the tax amount, and then later create a finalized invoice using POST /transactions (including all line items + tax collected).
Create credit transactions
To create a refund, we treat this as a separate transaction of typecredit. It has all the same line items and tax amounts (all positive amounts), but it just has the credit type.
As a utility, if a parent_transaction_id is provided, and no line_items are provided, we will pull in all the line items for the original transaction, effectively reversing the whole sale. This is for full refunds or credit memos. You can also just provide us the full line items again instead if there is no parent transaction yet.
If instead line_items are provided (even if a parent_transaction_id is present), we use those line items instead. This can be useful for partial refunds or partial credit memos.
What this looks like is very similar to the payment workflow:
- For a full refund, you simply wait for the refund event, and then do
POST /transactionswith a body of{ "type": "credit", "parent_transaction_id": "txn_123…", "status": "finalized", "tax_date": "2025-03-01T00:00:00Z" } - For a partial refund, you need to know how much tax to refund, so you can do a very similar approach as the payment workflow
- First do a calculation, either with
POST /calculations, or by creating a draft transaction. This outputs the tax. - Then, you refund the line items, plus the tax, in the payment system.
- Then, you either create a finalized transaction with the updated line items (and optional
parent_transaction_id), or you update the transaction with{ "status": "finalized" }.
- First do a calculation, either with