Integrate Connect
This guide demonstrates how to calculate taxes, record sales and refunds on behalf of your connected accounts, and alert your sellers when new tax collection obligations arise. These apply both to Standard and Custom accounts.
Here we assume you already developed the process to create a "connected account" when a user (seller, vendor, or service provider) sign up on your platform, so that you can calculate taxes and record transactions on their behalf.
If not, you can learn more about the different Connect flavors or connected account types here. To learn more about the process of creating connected accounts, which varies depending on the account's type, read "Onboard Standard accounts" and "Onboard Custom accounts".
1. Calculate tax rates
Every time one of your sellers 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 buyer's location (at least country and postal code), the product's tax code, and the seller's registered jurisdictions.
You can use our Tax Rates API with your seller's token to calculate tax rates on their behalf 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_SELLER_ACCESS_TOKEN}}"
There are different use cases that you might need to cover. Please read the "Calculate taxes on your backend" guide to learn more.
All the examples shown there will work with your connected account settings, by sending 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.
2. Record sales and refunds
Every time your platform processes either a sale or a refund for one of your sellers, 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 sellers when new tax collection obligations arise.
Use our Transactions API to record all your sales and refunds in Quaderno:
curl --request POST \
--url https://YOUR_MAIN_ACCOUNT_NAME.sandbox-quadernoapp.com/api/transactions
--header 'Authorization: Bearer YOUR_SELLER_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.
3. Alert on new tax obligations
To ensure that your users are notified when they exceed tax thresholds, we offer three types of events that you'll need to process:
threshold.warning- Occurs whenever a tax threshold is about to be reached. Useful for contacting the tax agency where the business will need to start filing taxes soon.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 must provide a webhook endpoint on your backend, 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_SELLER_ACCESS_TOKEN}} header.
Keep in mind that you will need to use the account_id provided when creating the connected account, in order to identify which webhook payload corresponds to which connected account.
Most platforms choose to alert their users in their own dashboard. Sending emails is also a good idea.
4. Generate tax reports
Every quarter (or every month), businesses need to file taxes in all the jurisdictions where they're registered. Quaderno can help generating tax reports for your sellers 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_SELLER_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_SELLER_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_SELLER_ACCESS_TOKEN}}"
Most platforms choose to download the reports and provide a download link for their users in their dashboard.
You've now harnessed the tax-compliance power of Quaderno Connect.