Settings

When planning your application or integration, there are many settings in Sage Business Cloud Accounting which should be considered. Settings are defined at a business and contact level and play a major role in the day to day operation of a business. For example, record and transaction settings allow users to define the number of days an invoice may be unpaid before it becomes outstanding. Using credit terms different to those outlined by the business may cause inaccuracies in cash flow forecasting and aged debtor reporting.

The following list represents the API endpoints containing details of settings pertinent to a business:

To help understand how settings are entwined in business transactions we have created common scenarios and use cases throughout the document.

Invoicing

The Sage Business Cloud Accounting API provides a conduit to create both sales and purchase invoice artefacts. Essential to invoice creation, a valid contact must be passed in the request. The selected contact may have specific settings which hierarchically take precedence over settings defined at a business level.

The below contacts endpoint response contains attribute values that allow us to determine if the contact or business setting values should be used.

{
  ...
  "credit_limit": "1500.0",
  "credit_days": 15,
  "credit_terms_and_conditions": "These terms are applied to the contact and "
                                 "should be used instead of globally defined "
                                 "Terms and Conditions",
  "product_sales_price_type": {
    "id": "fe12f4bad52345fa806fed44f5ec7fbb",
    "displayed_as": "Sales Price",
    "$path": "/product_sales_price_types/fe12f4bad52345fa806fed44f5ec7fbb"
  },
  ...
}

credit_days if defined, are used to set the due date of an invoice. If the value returned is null, the credit days defined in invoice_settings[customer_credit_days]/[vendor_credit_days] are used to calculate the invoice due_date. Fortunately, this is all dealt with by business logic, providing the invoice due_date in your POST or PUT request is not set. Setting this value will override all business logic and may result in an invoice with credit terms different to those defined for the contact or business.

credit_limit (Accounting only) is defined only at contact level. Setting this value does not invoke business logic to prevent new transactions exceeding the limit but acts as a reference to the user.

credit_terms_and_conditions (Accounting only) if defined, are used above those defined in invoice_settings[invoice_terms_and_conditions]. Unlike credit_days there is no business logic to apply the terms and conditions and the value must be passed in the request.

currency represents the currency type associated with the contact. It is only applicable if the business uses multi-currency (Accounting only).

product_sales_price_type (Accounting only) represents the id of the product price type associated with the contact. If product items are added to the invoice lines, the associated product price should be used to populate the unit price.

default_sales_ledger_account (Accounting only) represents the id of the default sales ledger account associated with the contact. If the scope of your integration includes the selection of ledger accounts, it is good practice to use the ledger account as the default selection.

default_purchase_ledger_account (Accounting only) represents the id of the default purchase ledger account associated with the contact. If the scope of your integration includes the selection of ledger accounts, it is good practice to use the ledger account as the default selection.

default_sales_tax_rate (Accounting only) represents the id of the default tax rate associated with the contact. If the scope of your integration includes the selection of tax rates, it is good practice to use the tax rate as the default selection.

sales_discount_ledger_account represents the id of the default ledger account used to post purchase discounts amounts to. If the scope of your integration includes invoice discounts, it is good practice to use this ledger account as the default selection.

purchase_discount_ledger_account represents the id of the default ledger account used to post sales discounts amounts to. If the scope of your integration includes invoice discounts, it is good practice to use this ledger account as the default selection.

carriage_ledger_account represents the id of the default ledger account used to post carriage amounts to. If the scope of your integration includes carriage or delivery charges, it is good practice to use this ledger account as the default selection.

Regional Differences for Invoicing

The fundamentals of creating and editing invoices are applicable to all of the supported Sage Business Cloud Accounting regions. Differences tend to be relative to invoice taxation and the different types of customers and suppliers. For example, in Spain you would need to consider an income tax for freelancers (IRPF) which is charged as a percentage of the total invoice value.

Exposed via the financial_settings endpoint the default_irpf_rate represents the percentage rate at which IRPF is applied to sales invoices.

Applicable to retailers, Recargo de equivalencia is a Spanish taxation whereby the retailer pays an additional tax percentage when they purchase goods from the wholesaler. If a contact is a retailer, you would need to display only recargo specific tax rates in any picker or selector control. Recargo contacts are identified from the contact record’s tax_calculation attribute which returns a Boolean defining whether or not the contact is a retailer.

It is probable that businesses dealing with contacts located in other countries of the world will have enabled the multi-currency setting within Sage Business Cloud (Accounting only). Understanding if the business uses multi-currency is possible via the Boolean value returned for the financial_settings, multi_currency_enabled attribute. If multi-currency is enabled, it is recommended to obtain the currency of the contact to ensure an accurate exchange rate is used for the invoice. The returned id of the contact’s currency can then be passed in a GET request to the exchange_rates endpoint to obtain stored rates for the currency.

Quotations & Estimates

Quotations and estimates are available only to customer contacts and, like invoices, have default setting values that need to be considered. Similar to the due_date of an invoice, quotes and estimates have an expiry date set at the point of creation. The invoice_settings endpoint returns attribute values for both the quote_default_days_to_expiry and estimate_default_days_to_expiry. Unlike invoices, the expiry date must be passed when posting a quote or estimate.

Allocating Payments on Account

Not all receipts and payments are allocated directly to an invoice in Sage Business Cloud Accounting. It is possible for a receipt or payment to appear on the contact balance as unallocated. Unallocated contact balances can be allocated via a POST request to the contact_allocations endpoint. A scenario causing this post to fail may occur if the business is registered under the VAT Cash Accounting scheme and the invoice line items have a different tax rate to the tax rate of the unallocated payment.

If the scope of your integration is to cover the allocation of payments and receipts, it is recommended that you confirm the VAT scheme of the business. A GET request to the financial_settings endpoint will return a response similar to the one below containing the tax_scheme attribute. If the tax_scheme id value is CASH_ACCOUNTING, it is recommended that the tax rates of both the invoice lines and receipt or payment are the same before attempting to POST the contact_allocations request. Attempting to allocate invoices to receipts and payments with differing tax rates will result in a 422 response, “Couldn’t find Sales Payable Artefact.”