Integrate Connect
This guide demonstrates how to calculate taxes, record sales and refunds on behalf of your connected accounts, and alerting them when new tax obligations arise. These apply both for Standard and Custom accounts.
For demonstration purposes, we’ll build a home-rental marketplace that connects homeowners to people looking for a place to rent. You can use the concepts covered in this guide in other applications as well.
The key point here is that almost all API actions can be performed on behalf of your connected users, by using an Authorization: Bearer header with their access token. Their account configuration will be applied for those actions.
Create a connected account
When a user (seller or service provider) signs up on your platform, create a user account (referred to as a connected account) so you can calculate taxes or record transactions on their behalf.
In our home-rental example, the connected account represents the homeowner.
There are two different types of connected accounts:
- Standard accounts are controlled directly by the account holder.
- Custom accounts are invisible to the account holder.
You can learn more about connected account types here.
The process to create connected accounts varies depending on the account's type. Read Onboard Standard accounts and Onboard Custom accounts to learn more.
Calculate tax rates
Every time the homeowner makes a sale, your platform must calculate the exact tax rate that needs to be applied to the transaction before taking the payment.
That tax rate is based on the customer's location (country and postal code) and the product's tax code, and the account's registered jurisdictions.
You can use our Tax Rates API to calculate tax rates during the checkout process:
curl https://quadernoapp.com/api/tax_rates/calculate?to_country=US&to_postal_code=90210&tax_code=eservice \
-H "Authorization: Bearer {{YOUR_USER_ACCESS_TOKEN}}"
There are different use cases that you might need to cover. To learn how, read the "Calculate taxes on your backend" guide.
All the examples shown there should work with your connected account, just by adding the Authorization: Bearer {{access_token}} header. That way your user's connected account configuration (registered jurisdictions, default product type and tax code, etc) will be used in the tax calculation.
Record sales and refunds
Every time your platform processes either a sale or a refund, you need to send the transaction's data to Quaderno in order to both issue invoices and credit notes, as well as being able to generate updated tax reports and alert your users when new tax obligations arise.
Use our Transactions API to record all your sales and refunds in Quaderno:
curl --request POST \
--url https://YOUR_MAIN_ACCOUNT_NAME.quadernoapp.com/api/transactions
--header 'Authorization: Bearer YOUR_USER_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"type": "sale",
"currency": "GBP",
"customer": {
"first_name": "Alex",
"last_name": "Wick",
"street_line_1": "67 Church Lane",
"city": "London",
"postal_code": "E94 7RT",
"country": "GB"
},
"items": [
{
"description": "Simple Software",
"amount": 9.90,
"tax": {
"country": "GB",
"rate": 20.0,
"tax_code": "eservice".
}
}
],
"payment": {
"method": "credit_card",
"processor": "yourPaymentProcessorName",
"processor_id": "yourPaymentProcessorId"
},
"evidence": {
"billing_country": "GB",
"ip_address": "255.255.255.255",
"bank_country": "GB"
},
"processor": "yourPlatformName",
"processor_id": "yourPlatformTransactionId"
}'
Check the guide "Record sales" to dig deeper on the objects shown on the API call.
To create refunds, the type: refund request will need to specify the same processor and processor_id used on the sale, as explained in this guide.
Alert on new tax obligations
To ensure that your users are notified when they exceed tax thresholds, we offer three types of events:
threshold.warning- Occurs whenever a tax threshold is about to be reached. Useful for contacting the tax agency where you'll need to start filing taxes soon (or your tax advisor).threshold.exceeded- Occurs whenever a tax threshold is reached. Useful for registering on the corresponding jurisdiction.threshold.eu.100k- Occurs whenever sales of digital services within the EU (exclusive of VAT) reach €100,000. Applies only to EU-based sellers.
To get these notifications, you need to provide a webhook endpoint on your end as well as create webhooks using our Webhooks API.
To create the webhooks, follow the instructions in the "Get real-time updates guide, but using an Authorization: Bearer {{YOUR_USER_ACCESS_TOKEN}} header. Keep in mind that you will need to use the account_id provided when creating the connected account to identify which webhook payload corresponds to which account.
Generate tax reports
Every quarter (or every month), businesses need to file taxes in all the jurisdictions they're registered. Quaderno can help generating tax reports for your users with all the information they need.
Our Reporting API works asynchronously. This means you'll create a Request object, and then you'll be able to get the report when it's ready, using its ID provided on the response:
curl https://quadernoapp.com/api/reporting/requests \
-H "Authorization: Bearer {{YOUR_USER_ACCESS_TOKEN}}"
-d report_type="tax_summary" \
-d parameters[from_date]="2023-05-01" \
-d parameters[from_date]="2023-05-31"
Depending on the complexity of the report, it may take some time to be generated. We recommend subscribing a webhook to the event reporting.request.succeeded, in order to be automatically notified when the report is ready:
curl https://quadernoapp.com/api/webhooks \
-H "Authorization: Bearer {{YOUR_USER_ACCESS_TOKEN}}" \
-d url="https://{{YOUR_WEBHOOK_URL}}" \
-d event_types[]="reporting.request.suceeded" \
-d event_types[]="reporting.request.failed" \
Finally, get the report request again using its ID, to get your user's report download URL from the report_url field.
curl https://quadernoapp.com/api/reporting/requests/REQUEST_ID \
-H "Authorization: Bearer {{YOUR_USER_ACCESS_TOKEN}}"