Use this method to retrieve either one or many manual journals.
| Date | Date journal was posted - YYYY-MM-DD |
| LineAmountTypes | See Line Amount Types |
| Status | See Manual Journal Status Codes |
| Narration | Description of journal being posted |
| JournalLines | See JournalLines. |
| Url | Url link to a source document – shown as "Go to [appName]" in the Xero app |
| ShowOnCashBasisReports | Boolean - default is true if not specified |
| HasAttachments | Boolean to indicate if a manual journal has an attachment |
| UpdatedDateUTC | Last modified date UTC format |
| Elements for Journal Lines. These elements are returned if they contain a value. | |
| LineAmount | total for line. Debits are positive, credits are negative value |
| AccountCode | See Accounts |
| 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. |
| TaxAmount | The calculated tax amount based on the TaxType and LineAmount |
| ManualJournalID | You can specify an individual record by appending the ManualJournalID to the endpoint, i.e. GET https://.../ManualJournals/{identifier} |
| 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) |
| page | e.g. page=1 – Up to 100 manual journals will be returned in a single API call with journal lines shown for each manual journal |
To utilise paging, append a page parameter to the URL e.g. ?page=1. If there are 100 records in the response you will need to check if there is any more data by fetching the next page e.g ?page=2 and continuing this process until no more results are returned. By using paging all the journal line details for each manual journal are returned which may avoid the need to retrieve each individual manual journal.
Example response for retrieving a collection of ManualJournals without paging
GET https://api.xero.com/api.xro/2.0/ManualJournals
<ManualJournals>
<ManualJournal>
<Date>2014-01-21T00:00:00</Date>
<Status>DRAFT</Status>
<LineAmountTypes>NoTax</LineAmountTypes>
<UpdatedDateUTC>2014-01-21T01:35:38.077</UpdatedDateUTC>
<ManualJournalID>99ff1108-2d9a-4955-ac7e-e705aa1b9547</ManualJournalID>
<Narration>Prepaid our insurance a year in advance</Narration>
<ShowOnCashBasisReports>true</ShowOnCashBasisReports>
</ManualJournal>
<ManualJournal>
<Date>2014-01-21T00:00:00</Date>
<Status>POSTED</Status>
<LineAmountTypes>NoTax</LineAmountTypes>
<UpdatedDateUTC>2014-01-21T01:37:07.92</UpdatedDateUTC>
<ManualJournalID>e5f09a63-62db-4739-af7c-1deda351ed5a</ManualJournalID>
<Narration>Prepaid our phone a year in advance</Narration>
<ShowOnCashBasisReports>true</ShowOnCashBasisReports>
</ManualJournal>
</ManualJournals>
Example response when retrieving a single manual journal
GET https://api.xero.com/api.xro/2.0/ManualJournals/c53ebb10-c046-471b-9919-29ac6b9fb977
<ManualJournals>
<ManualJournal>
<Date>2015-06-29T00:00:00</Date>
<Status>POSTED</Status>
<LineAmountTypes>Exclusive</LineAmountTypes>
<UpdatedDateUTC>2015-06-28T22:10:27.377</UpdatedDateUTC>
<ManualJournalID>c53ebb10-c046-471b-9919-29ac6b9fb977</ManualJournalID>
<Narration>Everything Journal</Narration>
<JournalLines>
<JournalLine>
<Description>Everything Journal</Description>
<TaxType>INPUT2</TaxType>
<TaxAmount>15.00</TaxAmount>
<LineAmount>100.00</LineAmount>
<AccountCode>310</AccountCode>
</JournalLine>
<JournalLine>
<Description>Everything Journal</Description>
<TaxType>INPUT2</TaxType>
<TaxAmount>-15.00</TaxAmount>
<LineAmount>-100.00</LineAmount>
<AccountCode>404</AccountCode>
</JournalLine>
</JournalLines>
<ShowOnCashBasisReports>true</ShowOnCashBasisReports>
<HasAttachments>false</HasAttachments>
</ManualJournal>
</ManualJournals>
| The following are mandatory for a PUT / POST request | |
| Narration | Description of journal being posted |
| JournalLines | See JournalLines. The JournalLines element must contain at least two individual JournalLine sub-elements. |
| The following are recommended for a PUT / POST request | |
| Date | Date journal was posted - YYYY-MM-DD. Defaults to the current date if not provided. |
| The following are optional for a PUT / POST request | |
| LineAmountTypes | NoTax by default if you don't specify this element. See Line Amount Types |
| 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 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. |
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.
Example request with minimum elements to add a new draft manual journal
POST https://api.xero.com/api.xro/2.0/ManualJournals
<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>
Example of a new draft manual journal with optional elements
POST https://api.xero.com/api.xro/2.0/ManualJournals
<ManualJournal>
<Date>2014-08-13</Date>
<Status>DRAFT</Status>
<Narration>Prepaid our phone a year in advance</Narration>
<LineAmountTypes>NoTax</LineAmountTypes>
<JournalLines>
<JournalLine>
<Description>Prepaid Annual Phone</Description>
<LineAmount>-1000.00</LineAmount>
<AccountCode>489</AccountCode>
<TaxType>NONE</TaxType>
<Tracking>
<TrackingCategory>
<Name>Region</Name>
<Option>South</Option>
</TrackingCategory>
</Tracking>
</JournalLine>
<JournalLine>
<Description>Prepayment</Description>
<LineAmount>1000.00</LineAmount>
<AccountCode>620</AccountCode>
<TaxType>NONE</TaxType>
<Tracking>
<TrackingCategory>
<Name>Region</Name>
<Option>North</Option>
</TrackingCategory>
</Tracking>
</JournalLine>
</JournalLines>
<ShowOnCashBasisReports>false</ShowOnCashBasisReports>
</ManualJournal>
You can upload up to 10 attachments(each up to 3mb in size) per manual journal, once the manual journal has been created in Xero. To do this you'll need to know the ID of the manual journal which you'll use to construct the URL when POST/PUTing a byte stream containing the attachment file. e.g. https://api.xero.com/api.xro/2.0/ManualJournals/f0ec0d8c-6fce-4330-bb3b-8306278c6fd8/Attachments/image.png. See the Attachments page for more details.
Example of uploading an attachment
POST /api.xro/2.0/ManualJournals/f0ec0d8c-4330-bb3b-83062c6fd8/Attachments/Image002932.png
Headers:
Authorization: OAuth...
Content Type: image/png
Content-Length: 10293
Body:
{RAW-IMAGE-CONTENT}