Skip to main content

​
Retries and network failures

Does Taxwire send webhooks? No. The API is synchronous: the response to POST /transactions is the saved transaction, with its Taxwire id, status and tax. Can I retry a quote? Yes. POST /calculations saves nothing, so retry it as often as you need. How do I retry recording a sale or refund? Always send a reference_id, derived from your own order or refund number. It must be unique in your account, and it is what stops a retry from recording the same sale twice. If POST /transactions fails or times out:
  1. Retry with the same body and the same reference_id.
  2. A 400 saying the reference_id already exists means a transaction with it was saved, most likely by your earlier attempt. Don’t retry under a new reference_id. Read the saved transaction with GET /transactions/by_reference_id/{reference_id}.
  3. A 404 from that lookup means nothing was saved, so retry the request.
Don’t use / in a reference_id. The lookup can’t find a reference_id that contains one, even URL-encoded as %2F, and returns 404 for a transaction that exists.
Without a reference_id, a retry after a timeout can record the sale twice. A reference_id stays taken even after its transaction is voided. Can I retry an update? A status change, yes: sending {"status": "void"} to a transaction that is already void succeeds. An update that also changes line_items, currency, transaction_date or discounts is only accepted while the transaction is a draft, so if the first attempt finalized it, the retry is refused with 400. Read the transaction with GET /transactions/{id} to see where it stands. Which errors should I retry? 429, 500, 502, 503 and 504, with exponential backoff. On a 429, wait the number of seconds in the Retry-After header first. Don’t retry other 4xx errors unchanged: fix the request. See Errors.

​
Refunds

Why is my refund refused with credit_remainder_unknown? Taxwire works out how much tax is left to refund on a sale from the tax recorded on the sale and on earlier credits against it. If the sale or an earlier credit has no tax recorded, the credit is refused with 422:
The usual cause is that the sale, or an earlier credit, is still a draft. A draft has no tax recorded, even if it was sent with a tax_amount. Finalize it with POST /transactions/{id} and {"status": "finalized"}, then send the credit again. If everything is already finalized, contact us with the sale’s id.

​
Rate limits

What is the limit? 10 requests per second per API key, by default. Is it per endpoint? No. Every request made with a key counts against that key’s one limit: quotes, transactions, refunds, lookups, customers and products alike. The limit is counted over a moving one-second window. How do I know how close I am? Successful responses carry two headers: What happens over the limit? The request is refused with 429 and a Retry-After header giving the seconds to wait. Nothing is processed, so the request is safe to retry after that. Can the limit be raised? Yes. Limits are set per account. If you expect more traffic, such as a sale or a launch, contact us with your expected peak and we’ll raise it.

​
Currency and exchange rates

Which currency is tax returned in? The transaction’s currency. A KRW order gets its tax in KRW, in the currency’s smallest unit. See currency support for the currencies we accept. Is an exchange rate used to calculate tax? Not for percentage taxes, which are most sales taxes and VAT: the rate is applied to your prices in your currency. Only a tax set as a fixed amount per unit (rate_type: flat_amount in the response) uses one. That amount is set in the jurisdiction’s currency, and Taxwire converts it to the transaction’s currency at the exchange rate for the transaction_date. Rates come from Open Exchange Rates and are updated daily. Can the tax change between quoting and recording because of exchange rates? Not for percentage taxes. The tax changes when the inputs change: the items, prices, discounts, addresses or transaction_date. It can also change if your account’s setup changes in between, for example a new registration or a customer’s exemption. Can a refund be in a different currency from its sale? No. A credit with line items in another currency is refused with 422, and a full refund always takes the sale’s currency. How are nexus thresholds tracked across currencies? Taxwire converts your sales into each threshold’s currency, USD for US states, at each day’s exchange rate. You don’t need to send converted amounts. Why does tax include a fraction of the smallest unit? Tax is calculated precisely, so a line’s tax can be, for example, "82.5" cents. Round the order’s tax_amount once, when you charge the buyer, rather than rounding each line.