FAQ - Frequently Asked Questions
Less than to read
This document outlines the most common issues raised by developers when working with the v3.1 API. Solutions to these issues that have resolved the query in most cases have been included, along with options for further support when required.
Where can I sign up for a free user/business account?
Trial accounts/businesses are created using the links found in the Quick Start Guide. The trial accounts last for only 30 days and can be extended for 12 month periods using the Extension Request Form.
By signing in, a cookie related to your country will be set. If you want to create a new trial account with a different country, you need to reset the country cookie. After visiting https://www.sageone.com/?clear, you will see the Show country selection (the ‘flag’ page) again.
Do you have demo accounts? When do trial accounts expire?
At present there is no demo/sandbox environment for development purposes. Trial accounts need to be created for each of the regions your app integrates with and will expire after 30 days.
What is an artefact?
An artefact can be one of the following resources:
- Purchase Corrective Invoice (🇪🇸 only)
- Purchase Credit Note
- Purchase Invoice
- Purchase Quick Entries
- Sales Corrective Invoice (🇪🇸 only)
- Sales Credit Note
- Sales Estimates
- Sales Invoice
- Sales Quick Entries
- Sales Quotes
All these entities cause transactions to be made, except for sales estimates, sales quotes and sales invoices with status DRAFT.
How do you pay an invoice using the API?
To post a customer receipt or supplier payment to pay an existing invoice you use the contact_payments endpoint.
When posting a payment, you can allocate it against an invoice by passing in the artefact_id of the invoice, this will then allocate against the invoice and mark the invoice as paid.
Additional examples/information can be found in the Sample JSON below:
POST /contact_payments
Content-Type: application/json
{
"contact_payment": {
"transaction_type_id": "CUSTOMER_RECEIPT",
"contact_id": "contact_id required",
"bank_account_id": "bank_account_id required",
"date": "01-01-2018",
"total_amount": 240,
"reference": "Ref 123",
"allocated_artefacts": [
{
"artefact_id": "sales_invoice_id required",
"amount": 240
}
]
}
}
Can I post a payment for a contact without allocating it to an invoice?
Yes. To post a payment that is not allocated against an invoice, using the following JSON. Both the contact_id and bank_acccount_id are required. This can then be allocated later using contact_allocation.
POST /contact_payments
Content-Type: application/json
{
"contact_payment": {
"transaction_type_id": "CUSTOMER_RECEIPT",
"contact_id": "contact_id required",
"bank_account_id": "bank_account_id required",
"date": "2018-01-01",
"total_amount": 240,
"reference": "Ref 123"
}
}
How can I allocate a credit note to an invoice?
If a credit note is posted using sales_credit_notes, it can be allocated to an invoice at that time or at a later date.
When you need to allocate the credit to the invoice you need to POST against contact_allocations, passing in the credit_id and the invoice_id as the artefacts as documented below.
POST /contact_allocations
Content-Type: application/json
{
"contact_allocation": {
"transaction_type_id": "CUSTOMER_ALLOCATION",
"contact_id": "CONTACT ID",
"allocated_artefacts": [
{
"artefact_id": "INVOICE ID",
"amount": 120
},
{
"artefact_id": "CREDIT ID",
"amount": -120
}
]
}
}
It is important to note if you are allocating a payment on account to an existing invoice, replace the credit_id with the payment_on_account_id of the contact_payment being allocated.
How can I see which transaction has been allocated to an invoice?
Using the show_payments_allocations query param on either a sales_invoices or purchase_invoices endpoint will return details of all payments allocated.
GET /sales_invoices/{id}?show_payments_allocations=true
Sample Partial Response:
{
"id": "2c1fd61570444e7bbf09f3940e2e11ea",
"displayed_as": "SI-23",
"$path": "/sales_invoices/2c1fd61570444e7bbf09f3940e2e11ea",
...
"payments_allocations": [
{
"links": [
{
"href": "https://accounts-extra.sageone.com/advanced_uk/customer_allocations/42582354",
"rel": "alternate",
"type": "text/html"
}
],
"date": "2018-01-01",
"type": "Allocation - Crn",
"reference": "SCN-112",
"amount": "240.0",
"discount": null,
"stripe_transaction_id": null,
"contact_allocation": {
"id": "30c3521298e8485b8f78c9763430fa7e",
"displayed_as": "2018-01-01",
"$path": "/contact_allocations/30c3521298e8485b8f78c9763430fa7e"
},
"artefact": {
"id": "1076d0a295614201b0d554bac40a96e2",
"displayed_as": "SCN-112",
"$path": "/sales_credit_notes/1076d0a295614201b0d554bac40a96e2",
"links": [
{
"href": "https://accounts-extra.sageone.com/invoicing/sales_credit_notes/1076d0a295614201b0d554bac40a96e2",
"rel": "alternate",
"type": "text/html"
}
]
},
"contact_payment": null,
"displayed_as": "Allocation - Crn (SCN-112)",
"negative_payment": null
}
],
...
}
Further Support
Are there any other resources for help?
Look for your issue, or write a query on our community forums found on Sage City.
This site gives access to the community forums, developer blog and allows connection with other developers using the Sage Accounting API. Creating a discussion around a query or issue can sometimes be the quickest way to receive support from Sage or the developer community, especially outside of the Developer Services support teams core hours (9:00 - 17:00 (UK time), Mon- Fri).
How do I log a support ticket?
Initially you should send an email requesting support to [email protected]. Try to be very clear about the issue faced, include what you are trying to do, error messages and troubleshooting you have already tried. Feel free to use screenshots where applicable.
It is especially helpful in diagnosing/troubleshooting issues if you can send us the full dump of both the request being sent to the API, and the full response. Ensure any Request-Id headers are also included.
If this query is urgent you need to call that out in the initial email, preferably along with a full business impact to assist us with prioritizing the incident if we can.
If this is the first time you have contacted developer services, it is possible we will not hold an internal CRM account for you. In this case you will be asked for the following details:
First Name (of Primary Contact):
Last name (of Primary Contact):
Company name:
Address:
Email address:
Telephone number:
Once we have them, we will have an account created and your ticket will be logged.
If you have not already setup a trial account for the Sage Business Cloud Accounting application to use with your development, please let us know so that we can organize that for you and have it extended to a developer account which will grant access for multiple years.