Manual Journals
| URL | https://api.xero.com/api.xro/2.0/ManualJournals |
| Methods Supported | GET, PUT, POST |
| Description | Allows you to retrieve any manual journals Allows you to add or update draft or posted manual journals |
Elements for ManualJournals
| The following are mandatory for a PUT / POST request | |
| <Narration> | Description of journal being posted |
| <JournalLines> | See JournalLines |
| The following are recommended for a PUT / POST request | |
| <Date> | Date journal was posted – YYYY-MM-DD |
| The following are optional for a PUT / POST request | |
| <Status> | See Manual Journal Status Codes |
| <Url> | Url link to a source document – shown as “Go to [appName]” in the Xero app |
| <ShowOnCashBasisReports> | Boolean – default is true if not specified |
Elements for Journal Lines
The <JournalLines> element must contain at least two individual <JournalLine> sub-elements.
| These elements are returned on a GET request if they contain a value. | |
| The following are mandatory for a PUT / POST request | |
| <LineAmount> | total for line. Debits are positive, credits are negative value |
| <AccountCode> | See Accounts |
| The following are optional for a PUT / POST request | |
| <Description> | Description for journal line |
| <TaxType> | Used as an override if the default Tax Code for the selected <AccountCode> is not correct – see TaxTypes. |
| <Tracking> | Optional Tracking Category – see Tracking. Any JournalLine can have a maximum of 2 <TrackingCategory> elements. |
POST ManualJournals
Use this method to create or update a manual journal with a DRAFT status or POSTED status.
Example of minimum elements required to add a new draft manual journal
<ManualJournal>
<Narration>Accrued expenses - prepaid insurance adjustment for January 2011</Narration>
<JournalLines>
<JournalLine>
<LineAmount>55.00</LineAmount>
<AccountCode>433</AccountCode>
</JournalLine>
<JournalLine>
<LineAmount>-55.00</LineAmount>
<AccountCode>620</AccountCode>
</JournalLine>
</JournalLines>
</ManualJournal>
There are a few accounts that you can’t use when entering manual journals in Xero. These include system accounts (accounts receivable, accounts payable & retained earnings) and bank accounts. You will receive a 400 validation error if you try and use these reserved accounts. Consider setting up one or more clearing accounts if you need to journal to a bank account.
A PUT or POST manual journal can contain a maximum of 100 journal lines.
PUT ManualJournals
The PUT method is similar to the POST ManualJournals method, however you can only create new manual journals with this method.
GET ManualJournals
Use this method to retrieve either one or many manual journals.
Optional parameters
| Record filter | You can specify an individual record by appending the value to the endpoint, i.e. GET https://…/ManualJournals/{identifier} |
| JournalID – The Xero identifier for a Manual Journal e.g. 297c2dc5-cc47-4afd-8ec8-74990b8761e9 |
|
| Modified After | The ModifiedAfter filter is actually an HTTP header: ‘If-Modified-Since‘. A UTC timestamp (yyyy-mm-ddThh:mm:ss) . Only manual journals created or modified since this timestamp will be returned e.g. 2009-11-12T00:00:00 |
| Where | Filter by an any element (see Filters) |
| order | Order by any element returned (see Order By) |
Examples for GET ManualJournals
Example 1. This is an example response when a filter has been applied to request just a single manual journal. In this case the ManualJournalID of 1e6b1916-6d82-4fa2-96f8-f17b33641538 was specified.
<ManualJournals>
<ManualJournal>
<Date>2011-01-31T00:00:00</Date>
<Status>DRAFT</Status>
<LineAmountTypes>NoTax</LineAmountTypes>
<UpdatedDateUTC>2011-02-07T20:26:28.757</UpdatedDateUTC>
<ManualJournalID>1e6b1916-6d82-4fa2-96f8-f17b33641538</ManualJournalID>
<Narration>Accrued expenses - prepaid insurance adjustment for January 2011</Narration>
<JournalLines>
<JournalLine>
<Description>Accrued expenses - prepaid insurance adjustment for January 2011</Description>
<TaxType>NONE</TaxType>
<LineAmount>55.00</LineAmount>
<AccountCode>433</AccountCode>
</JournalLine>
<JournalLine>
<Description>Accrued expenses - prepaid insurance adjustment for January 2011</Description>
<TaxType>NONE</TaxType>
<LineAmount>-55.00</LineAmount>
<AccountCode>620</AccountCode>
</JournalLine>
</JournalLines>
</ManualJournal>
</ManualJournals>