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

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
<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
The following are only returned on a GET request
<HasAttachments> Boolean to indicate if a manual journal has an attachment

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 – minimum elements

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>

Example – more elements

Example of a new draft manual journal with more elements

<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>

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.

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.

e.g.

POST /api.xro/2.0/ManualJournals/f0ec0d8c-4330-bb3b-83062c6fd8/Attachments/Image002932.png
Authorization: OAuth...
Content Type: image/png
Content-Length: 10293

{RAW-IMAGE-CONTENT}

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 retrieving Manual Journals that have been modified since a timestamp. Note than when a collection of manual journals is returned, each journal is shown in summary form without the line item detail. You need to request an individual manual journal to see all the line items (see example #2 below). The Journals endpoint is more suitable if you are trying to retrieve all journals in an organisation (rather than just manually created ones).

<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 2. 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. Note the full line item detail is returned.

<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>