Skip to main content

Record sales

To automate the issuance of your invoices, provide notifications when taxes need to be collected in another country, and generate tax reports, Quaderno requires you to track all of your sales through the Transactions API.

The process is straightforward. Simply send your sales data via a POST call to the /transactions endpoint, as shown in the example below:

curl --request POST \
  --url https://ACCOUNT_NAME.quadernoapp.com/api/transactions
  --header 'Authorization: Basic ENCODED_API_KEY' \
  --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"
}'

Next, let's review some of the objects in the call. For more information, please refer to our API reference.

Customer​

This object contains your customer's data. You can reuse an existing customer in your Quaderno account by simply sending its ID, or create a new customer. In the latter case, you must include all the customer's billing data, as shown in this example.

"customer": {
  "first_name": "Alex",
  "last_name": "Wick",
  "street_line_1": "67 Church Lane",
  "city": "London",
  "postal_code": "E94 7RT",
  "country": "GB"
}

Items​

This object should contain a list of all products sold in the transaction, including any applicable taxes. For example, if you were selling software to a customer in London, you might include the following:

"items": [
  {
  "description": "Simple Software",
    "amount": 9.90,
    "tax": {
      "country": "GB",
      "rate": 20.0,
      "tax_code": "eservice".
    }
  }
]

The tax information can be obtained directly from the API for calculating taxes.

Payment​

This section contains data related to the payment:

"payment": {
  "method": "credit_card",
  "processor": "yourPaymentProcessorName",
  "processor_id": "yourPaymentProcessorId"
}

Evidence​

This object contains evidence of the customer's location, which can be used to justify the tax calculation applied in the event of a possible inspection by the tax authorities:

"evidence": { 
  "billing_country": "US", 
  "ip_address": "255.255.255.255", 
  "bank_country": "US" 
}

Platform data​

To handle future returns for this sale, make sure to include your platform’s name and your internal transaction ID in the fields processor and processor_id, respectively.

Invoice generated​

Every time you record a transaction, Quaderno will return the data of the new invoice assigned to the sale. You can use the following parameters to send the invoice to your customer:

  • pdf: URL of the invoice in PDF format.
  • permalink: URL of the invoice in HTML format.

Examples of responses can be found in the API reference.