This guide outlines how to use the Xledger GraphQL API efficiently and avoid unnecessary consumption. It should be read alongside your integration specification and followed when designing or reviewing any API-based integration.
GraphQL Usage and Subscription Allowance
Use of the GraphQL API is included within your standard monthly Xledger software subscription, subject to the following usage limits:
Included each month:
- 5,000 GraphQL requests
- 1,000 MB downloaded via GraphQL
- 1,000 MB uploaded via GraphQL
If usage exceeds these included allowances, the following charges apply:
- £0.01 per additional request
- £0.10 per additional MB transferred
GraphQL usage is consumption-based. Designing queries properly (batching, filtering, pagination, only requesting required fields) will significantly reduce both cost and system load.
Batch Imports Sensibly
Where possible, send related records together in one request instead of many small ones.
Group corresponding lines together
If you are importing an invoice or journal, include the header and all associated lines in the same batch or mutation where supported.
Benefits:
- Fewer API calls and reduced load on API.
- Clearer error handling when a document fails.
Example:
mutation {
addGLImportItems(
inputs: [
{
node: {
trRegNumber: 20260217
postedDate: "2026-02-17"
invoiceDate: "2026-02-17"
transactionSource: { code: "GL" }
dueDate: "2027-01-01"
amount: "101.00"
invoiceAmount: "101.00"
text: "Invoice Xledger Test - Line 1"
invoiceNumber: "Xledger123"
jobLevel: { dbSubId: 1 }
account: { code: "1010" }
}
}
{
node: {
trRegNumber: 20260217
postedDate: "2026-02-17"
invoiceDate: "2026-02-17"
transactionSource: { code: "GL" }
dueDate: "2027-01-01"
amount: "-101.00"
invoiceAmount: "-101.00"
text: "Invoice Xledger Test - Line 1"
invoiceNumber: "Xledger123"
jobLevel: { dbSubId: 1 }
account: { code: "1010" }
}
}
{
node: {
trRegNumber: 20260217
postedDate: "2026-02-17"
invoiceDate: "2026-02-17"
transactionSource: { code: "GL" }
dueDate: "2027-01-01"
amount: "102.00"
invoiceAmount: "102.00"
text: "Invoice Xledger Test - Line 2"
invoiceNumber: "Xledger123"
jobLevel: { dbSubId: 1 }
account: { code: "1010" }
}
}
{
node: {
trRegNumber: 20260217
postedDate: "2026-02-17"
invoiceDate: "2026-02-17"
transactionSource: { code: "GL" }
dueDate: "2027-01-01"
amount: "-102.00"
invoiceAmount: "-102.00"
text: "Invoice Xledger Test - Line 2"
invoiceNumber: "Xledger123"
jobLevel: { dbSubId: 1 }
account: { code: "1010" }
}
}
{
node: {
trRegNumber: 20260217
postedDate: "2026-02-17"
invoiceDate: "2026-02-17"
transactionSource: { code: "GL" }
dueDate: "2027-01-01"
amount: "103.00"
invoiceAmount: "103.00"
text: "Invoice Xledger Test - Line 3"
invoiceNumber: "Xledger123"
jobLevel: { dbSubId: 1 }
account: { code: "1010" }
}
}
{
node: {
trRegNumber: 20260217
postedDate: "2026-02-17"
invoiceDate: "2026-02-17"
transactionSource: { code: "GL" }
dueDate: "2027-01-01"
amount: "-103.00"
invoiceAmount: "-103.00"
text: "Invoice Xledger Test - Line 3"
invoiceNumber: "Xledger123"
jobLevel: { dbSubId: 1 }
account: { code: "1010" }
}
}
{
node: {
trRegNumber: 20260217
postedDate: "2026-02-17"
invoiceDate: "2026-02-17"
transactionSource: { code: "GL" }
dueDate: "2027-01-01"
amount: "104.00"
invoiceAmount: "104.00"
text: "Invoice Xledger Test - Line 4"
invoiceNumber: "Xledger123"
jobLevel: { dbSubId: 1 }
account: { code: "1010" }
}
}
{
node: {
trRegNumber: 20260217
postedDate: "2026-02-17"
invoiceDate: "2026-02-17"
transactionSource: { code: "GL" }
dueDate: "2027-01-01"
amount: "-104.00"
invoiceAmount: "-104.00"
text: "Invoice Xledger Test - Line 4"
invoiceNumber: "Xledger123"
jobLevel: { dbSubId: 1 }
account: { code: "1010" }
}
}
]
) {
edges {
node {
dbId
}
}
}
}
Choose sensible batch sizes
Avoid sending single records in a loop if processing large volumes. Use moderate batch sizes (e.g. 50–250 records depending on payload size).
Balance:
- Too small = unnecessary network traffic.
- Too large = risk of timeouts and complex error handling.
Only Request the Fields You Need
One of the key advantages of GraphQL is that you control exactly which fields are returned.
Best practice:
- Include only fields required for mapping or processing.
- Remove development-only fields before go-live.
- Smaller responses mean faster integrations.
Use Pagination Correctly
Always use cursor-based pagination when retrieving collections of data.
Recommended approach:
- Call the query with a defined page size (e.g. first: 100).
- Process returned results.
- If pageInfo.hasNextPage is true, call again using Cursor.
- Repeat until no further pages remain.
- Pagination prevents timeouts and reduces memory usage
Example:
Filter by Modified Date
Avoid retrieving all records on every run. Instead, use a modified date filter to retrieve only records changed since your last successful integration run.
Best practice:
- Store the timestamp of the last successful run.
- Use modifiedAt or equivalent filter in your next query.
Handle Errors and Retries Sensibly
- Validate data before sending to reduce failed requests. For example, checking all objects that are being referenced in the mutation all exist. Objects such as subledgers, projects, products etc.
- Log key identifiers (dbId) and error messages, this will help when debugging any failed records.
- Use exponential backoff for retries (e.g. 1s, 2s, 4s).
- Do not retry validation or permission errors repeatedly.
Respect Rate Limits and Scheduling
- Avoid excessive parallel calls.
- Schedule large jobs outside peak hours where possible.
- Implement backoff if rate limits are encountered.
Monitor Your GraphQL Usage
Xledger provides a GraphQL usage screen where you can review:
- Number of requests made
- Data downloaded (MB)
- Data uploaded (MB)
- Usage trends across the month
We recommend reviewing this screen at least monthly, particularly:
- After deploying a new integration
- After making changes to queries or batch sizes
- If usage appears higher than expected
Regular monitoring helps you:
- Detect unintended query loops
- Identify inefficient queries returning excessive data
- Prevent unexpected overage charges
- Optimise integrations before issues escalate
If you notice unusually high request counts or data volumes, review:
- Pagination logic
- Modified date filtering
- Batch sizes
- Whether queries are being repeatedly triggered in error
Identifying issues early prevents unnecessary consumption and avoids time spent debugging avoidable problems. To access this screen, you will need a user role which gives you access to the administration tab in the UI. Please see menu path below:
Administration -> System Access -> GraphQL -> GraphQL Usage Log
Security Best Practices
- Store API credentials securely.
- Use least-privilege roles and rotate credentials regularly.
- Do not log sensitive data or secrets.
Go-Live Checklist
- Queries only request required fields.
- Pagination implemented using pageInfo.
- Modified date filtering in place.
- Batch sizes tested and optimised.
- Error handling and retry logic configured.
- Logging includes IDs and error messages only.