Skip to content
Developerhome
Product homepage
Accounting
API Status:

Checking…

Artefact Statuses

  Less than to read

Overview

In Sage Business Cloud Accounting, the term artefact is used to define posted transactions which have a lifecycle and require some form of processing. For example a Sales Invoice can be unpaid, part paid or paid and it is the influence of processing payments which creates the change in status. Another defining artefact attribute is the ability to attach documents. Below is a list of artefact classified transactions.

  • Sales Quotes
  • Sales Invoices
  • Sales Credit Notes
  • Sales Corrective Invoices
  • Purchase Invoices
  • Purchase Credit Notes
  • Purchase Corrective Invoices

Sage Business Cloud Accounting has many features and functions to help and support business owners with the efficient running of their enterprise. Understanding the status of individual transactions can provide an efficient method of filtering data for task orientated prurposes. For example, there could be a number of quotes in the pipeline which have recently expired and require chasing or an invoice which is overdue for payment and prevents future purchases from the supplier due to the credit limit being exceeded.

SENT (Customer Artefacts)

Competing for and winning business would prove fruitless if the customer was not in receipt of the quotation or estimate to accept your offer and likewise, the chasing of invoice payment for an invoice the customer has not received. To denote when an artefact has been emailed or printed, a sent status is provided as an attribute of the artefact response in addition to the status of the artefact.

The Sage Business Cloud Accounting web app also consumes a 3rd party email service to provide further information relating to the status of the sent email. Users are informed if the email bounced, has been opened or in the case of a Sales invoice, if the hosted invoice link has been viewed. The API does not currently expose the email service status.

Sales Quotes & Estimates

Competing for and obtaining business is essential to business cashflow, and accurately predicting cashflow is equally important to the success and growth of a business. To help predict cashflow from pipeline, Sage Business Cloud Accounting provides helpful statuses to identify where a quotation or estimate is within its lifecycle.

DRAFT

It is possible to save new sales quotes and invoices in a draft state. Draft state is often used if the quote/estimate cannot be completed at the time of creation. The customer may wish to add more items or work but is undecided at that point in time or, they may have insufficient customer information to fully process and issue the artefact.

It is not possible to change the status of a quote/estimate to DRAFT, the quote/estimate is only ever created as DRAFT. Draft sales quotes/estimates are created by passing a status_id of DRAFT in the POST request. At present, the API does not allow a draft quote/estimate status to be changed.

PENDING

On creating a Sales Quote or Estimate the status will be set to ‘Pending’. The pending status informs the user that the quote or estimate has not passed its expiry_date, or, has not been declined or invoiced. This status can be filtered by users to provide a focused list of high probability opportunities to chase.

DECLINED

After considering a quote or estimate the customer may decide to decline the offer. If this occurs the status of the quote or estimate is set to ‘Declined’ and can be filtered to provide a list of declined quotes and estimates which could be used to provide important feedback on why the customer rejected the offer. Was it Price? Delivery time? Or a change to the customer’s requirements?

It is possible to decline a pending or expired sales quote/estimate by passing a status_id of DECLINED in a PUT request. The declined status of a quote/estimate can be removed by passing a status_id of PENDING in a PUT request.

PUT /sales_quotes/{id}

INVOICED

When a customer accepts the quote/estimate the artefact is converted to an invoice. The process of converting a quote/estimate to invoice is irreversible. The quote/estimate is converted to a sales invoice by passing the original_quote_estimate_id parameter with the id of the sales quote/estimate in addition to the other sales invoice parameters when making a POST request to the sales_invoices endpoint.

POST /sales_invoices?original_quote_estimate_id={id}

Sales & Purchase Artefacts

Sage Business Cloud Accounting helps make invoice and credit management more efficient by tagging artefacts with meaningful statuses allowing the easy identification of overdue and problem transactions. The artefacts together with their status are retuned via a GET request to the sales/purchase invoice or sales/purchase credit notes endpoints.

GET /sales_invoices?attributes=status
GET /purchase_invoices?attributes=status
GET /sales_credit_notes?attributes=status
GET /purchase_credit_notes?attributes=status

DRAFT (Sales invoices only)

It is possible to save new sales invoices in a draft state. Draft state is often used if the invoice cannot be completed at the time of creation. The customer may wish to add more items or work but is undecided at that point in time or, they may have insufficient customer information to fully process and issue the artefact. Invoices with a status of draft do not affect ledger balances.

It is not possible to change the status of a sales invoice to DRAFT, the status must be set on creation by passing a status_id of DRAFT in the POST request. Draft sales invoices can be converted to an unpaid sales invoice by adding release on a POST request.

POST /sales_invoices/{id}/release

PRO-FORMA (Sales Invoices only)

A Pro-Forma is a preliminary invoice sent to the customer ahead of delivery and is set with a status of PRO-FROMA. Once the customer agrees the content, the pro-forma can then be changed to an invoice. The value of the pro-forma does not affect the ledger balances.

It is not possible to change the status of a sales invoice from any other status other than DRAFT to PRO-FORMA and the status must be set on creation. Pro-Forma sales invoices are created by passing a status_id of PRO_FORMA in the POST request and are converted to unpaid sales invoices by passing a status of UNPAID in a PUT request.

PUT /sales_invoices/{id}
Content-Type: application/json

{
  "sales_invoice": {
    "status": "UNPAID"
  }
}

UNPAID (Sales/Purchases Invoices/Credits)

On creating a new sales/purchase artefact, the status will be set as unpaid. The unpaid status remains until the artefact is allocated to an acceptable payment/receipt or invoice/credit.

Business logic controls the setting of all statuses excluding void, or in the case of purchase invoices/credits, deleted. The void and deleted status is set by making a DELETE post to the relevant endpoint, along with the void_reason which is passed as an additional parameter. The void_reason is free text and provides the reason the artefact has been voided.

DELETE /sales_invoices/{id}?void_reason=Add_text_for_the_reason
DELETE /sales_credit_notes/{id}?void_reason=Add_text_for_the_reason
DELETE /purchase_invoices/{id}
DELETE /purchase_credit_notes/{id}

The PAID status refers to the artefact being fully paid. In the event of payments being deleted, it is possible for an invoice to revert to an UNPAID or PARTPAID status.

PARTPAID (Sales/Purchases Invoices/Credits)

The Part Paid status is seen when an allocation has been made which does not amount to the full outstanding_amount. The Part Paid status changes only if the allocated transaction or transactions were subsequently deleted.

DISPUTED (Purchase Invoices/Credits)

The Disputed status is applicable only to purchase artefacts and is used to flag disagreement with supplier invoices or credits. Unlike all other statuses, a status of disputed can be manually set providing the invoice is not paid. The method of setting and removing the disputed status is outside the current API scope and is set and removed from the web application.

VOID (Sales Invoices/Credits)

Legislation dictates sales artefacts cannot be deleted from an accounting system and must be visible for audit inspection. To accommodate legislation, sales invoices and credits are voided rather than deleted. When this occurs the status of the sales artefact is changed to VOID. This allows the artefact to remain visible for compliance but excludes the values of the transaction in the ledgers. As default, sales artefacts with a status of VOID are returned in the GET request to the sales_invoices endpoint.

GET /sales_invoices

DELETED (Purchase Invoices/Credits)

Deleted purchase artefacts are not returned in the response for purchase_invoices or purchase_credits. If an app or integration is maintaining a localized representation of data and has a requirement to remove deleted artefacts, query parameters can be passed in a GET request which allow deleted artefacts to be returned.

Querying & Filtering Artefacts

Maintaining and synchronizing localized representations of artefact data is made easier with the API’s querying and filtering capabilities. For example, if the requirement is to provide a list of expired sales_quotes, the status_id can be passed as a parameter in the GET request.

GET /sales_quotes?status_id=EXPIRED

Responses can be further refined with the use of query parameters relative to certain events. For example, if you wanted to return only purchase invoices deleted since a specific time, the deleted_since query parameter is added to the request along with the value.

GET /sales_invoices?deleted_since=2019-01-10T12:00:00Z

If the requirement is to return new or modified artefacts the updated_or_created_since query parameter can help make integrations and apps more performant and efficient.

GET /sales_invoices?updated_or_created_since=2019-01-10T12:00:00Z