Skip to main content

Integrate Connect

This guide demonstrates how to calculate taxes, record sales and refunds, and alert your sellers when new tax collection obligations arise. These steps apply to both Standard and 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 payment. This 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 the Tax Rates API with your seller's access token to calculate tax rates on their behalf during the checkout process:

curl https://sandbox-quadernoapp.com/api/tax_rates/calculate?to_country=US&to_postal_code=90210&tax_code=eservice \
  -H "Authorization: Bearer {{YOUR_SELLER_ACCESS_TOKEN}}"

2. Record sales and refunds​

After a sale or refund is processed on your platform, you need to send the transaction data to Quaderno. This step is essential for issuing invoices and credit notes, generating tax reports, and alerting your sellers about new tax collection obligations.

Use the Transactions API to record 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"
  }'
warning

To create refunds, the type should be refund, and the request must specify the same processor and processor_id used for the original sale.

3. Alert on new tax obligations​

To ensure your users are notified when they exceed tax thresholds, you must subscribe to our webhook events. These notifications allow you to alert your users when their business is nearing or has reached a new tax obligation.

The three primary events you'll need to process are:

  • threshold.warning: Occurs when a tax threshold is about to be reached.
  • threshold.exceeded: Occurs when a tax threshold is reached.
  • threshold.eu.100k: Occurs when digital sales within the EU reach €100,000 (applies to EU-based sellers only).

To receive these notifications, you must provide a publicly accessible webhook endpoint on your backend and create webhooks using our Webhooks API.

Most platforms choose to alert their users directly in their own dashboard or via email.

4. Generate tax reports​

At the end of each quarter or month, businesses need to file taxes in all jurisdictions where they are registered. Quaderno helps by generating detailed tax reports for your sellers.

The Reporting API works asynchronously. You will first create a Request object and then retrieve the report when it is ready.

curl https://sandbox-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"

Because generating a report can take time, we recommend subscribing to the reporting.request.succeeded webhook event to be notified automatically when the report is ready.

Finally, get the report request again using its ID to retrieve the user's report download URL from the report_url field.

curl https://sandbox-quadernoapp.com/api/reporting/requests/REQUEST_ID \
  -H "Authorization: Bearer {{YOUR_SELLER_ACCESS_TOKEN}}"

Most platforms choose to download the reports and provide a link for their users directly in their dashboard.

🎉 Congratulations! You've now harnessed the tax-compliance power of Quaderno Connect.