Xero: Retrieves a specific journal using a unique journal number

← Accounting operations · Get started

Operation xero.getjournalbynumber

Provider route: GET /api.xro/2.0/Journals/{JournalNumber}. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/xero with npm, or alter-sdk-xero with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { XeroIntegration } from "@alter-ai/xero";

async function execute(input: Parameters<XeroIntegration["accounting"]["getJournalByNumber"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new XeroIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.accounting.getJournalByNumber(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_xero import XeroIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = XeroIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.accounting.get_journal_by_number(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.JournalNumber	integer	Required within parent
headers	object	Required within parent	Additional keys: not allowed
headers.xero-tenant-id	string	Required within parent

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Retrieves journals — response body

Referenced models: Retrieves journals — response body

Schemas

Retrieves journals — response body

Field	Type	Presence	Description and constraints
$	object	Root
Journals	array	Optional
Journals[]	Model	Each item	Expand Retrieves journals — response body — Journals item
Warnings	array	Optional	Displays array of warning messages from the API
Warnings[]	Model	Each item	Expand Retrieves journals — response body — Warnings item

Referenced models: Retrieves journals — response body — Journals item, Retrieves journals — response body — Warnings item

Retrieves journals — response body — Journals item

Field	Type	Presence	Description and constraints
$	object	Root
CreatedDateUTC	string	Optional	Created date UTC format Read only: true
JournalDate	string	Optional	Date the journal was posted
JournalID	string	Optional	Xero identifier Format: uuid
JournalLines	array	Optional	See JournalLines
JournalLines[]	Model	Each item	Expand Retrieves journals — response body — Journals item Journal Lines item
JournalNumber	JSON	Optional
JournalNumber (anyOf 1)	integer	Alternative	Xero generated journal number
JournalNumber (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
Reference	string	Optional	reference field for additional indetifying information
SourceID	string	Optional	The identifier for the source transaction (e.g. InvoiceID) Format: uuid
SourceType	string	Optional	The journal source type. The type of transaction that created the journal Known values: ACCREC, ACCPAY, ACCRECCREDIT, ACCPAYCREDIT, ACCRECPAYMENT, ACCPAYPAYMENT, ARCREDITPAYMENT, APCREDITPAYMENT, CASHREC, CASHPAID, TRANSFER, ARPREPAYMENT, APPREPAYMENT, AROVERPAYMENT, APOVERPAYMENT, EXPCLAIM, EXPPAYMENT, MANJOURNAL, PAYSLIP, WAGEPAYABLE, INTEGRATEDPAYROLLPE, INTEGRATEDPAYROLLPT, EXTERNALSPENDMONEY, INTEGRATEDPAYROLLPTPAYMENT, INTEGRATEDPAYROLLCN

Referenced models: Retrieves journals — response body — Journals item Journal Lines item

Retrieves journals — response body — Warnings item

Field	Type	Presence	Description and constraints
$	object	Root
Message	string	Optional	Validation error message

Retrieves journals — response body — Journals item Journal Lines item

Field	Type	Presence	Description and constraints
$	object	Root
AccountCode	string	Optional	See Accounts
AccountID	string	Optional	See Accounts Format: uuid
AccountName	string	Optional	See AccountCodes
AccountType	string	Optional	See Account Types Known values: BANK, CURRENT, CURRLIAB, DEPRECIATN, DIRECTCOSTS, EQUITY, EXPENSE, FIXED, INVENTORY, LIABILITY, NONCURRENT, OTHERINCOME, OVERHEADS, PREPAYMENT, REVENUE, SALES, TERMLIAB, PAYG
Description	string	Optional	The description from the source transaction line item. Only returned if populated.
GrossAmount	JSON	Optional
GrossAmount (anyOf 1)	number	Alternative	Gross amount of journal line (NetAmount + TaxAmount). Format: double
GrossAmount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
JournalLineID	string	Optional	Xero identifier for Journal Format: uuid
NetAmount	JSON	Optional
NetAmount (anyOf 1)	number	Alternative	Net amount of journal line. This will be a positive value for a debit and negative for a credit Format: double
NetAmount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
TaxAmount	JSON	Optional
TaxAmount (anyOf 1)	number	Alternative	Total tax on a journal line Format: double Read only: true
TaxAmount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
TaxName	string	Optional	see TaxRates
TaxType	string	Optional	The tax type from taxRates
TrackingCategories	array	Optional	Optional Tracking Category – see Tracking. Any JournalLine can have a maximum of 2 <TrackingCategory> elements.
TrackingCategories[]	Model	Each item	Expand Create tracking categories — response body — Tracking Categories item

Referenced models: Create tracking categories — response body — Tracking Categories item

Create tracking categories — response body — Tracking Categories item

Field	Type	Presence	Description and constraints
$	object	Root
Name	string	Optional	The name of the tracking category e.g. Department, Region (max length = 100) Maximum length: 100
Option	string	Optional	The option name of the tracking option e.g. East, West (max length = 100) Maximum length: 100
Options	array	Optional	See Tracking Options
Options[]	Model	Each item	Expand Creates options for a specific tracking category — response body — Options item
Status	string	Optional	The status of a tracking category Known values: ACTIVE, ARCHIVED, DELETED
TrackingCategoryID	string	Optional	The Xero identifier for a tracking category e.g. 297c2dc5-cc47-4afd-8ec8-74990b8761e9 Format: uuid
TrackingOptionID	string	Optional	The Xero identifier for a tracking option e.g. dc54c220-0140-495a-b925-3246adc0075f Format: uuid

Referenced models: Creates options for a specific tracking category — response body — Options item

Creates options for a specific tracking category — response body — Options item

Field	Type	Presence	Description and constraints
$	object	Root
Name	string	Optional	The name of the tracking option e.g. Marketing, East (max length = 100) Maximum length: 100
Status	string	Optional	The status of a tracking option Known values: ACTIVE, ARCHIVED, DELETED
TrackingCategoryID	string	Optional	Filter by a tracking category e.g. 297c2dc5-cc47-4afd-8ec8-74990b8761e9 Format: uuid
TrackingOptionID	string	Optional	The Xero identifier for a tracking option e.g. ae777a87-5ef3-4fa0-a4f0-d10e1f13073a Format: uuid

Policy, approvals and errors

SDK function policy ID: xero.getjournalbynumber. Catalog operation: getJournal. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Official provider source