Manual Journals


Overview

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
Allows you to attach files to a manual journal

GET ManualJournals

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

Optional parameters

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

Paging ManualJournals (recommended)

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>

POST ManualJournals

Use this method to create or update a manual journal.
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.

PUT ManualJournals

The PUT method is similar to the POST ManualJournals method, however you can only create new manual journals with this method.

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>

Uploading an Attachment

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}