Sage Business Cloud API Essential Guide

Aug 11, 2024 • 6 minute read

What type of API does Sage Business Cloud provide?

Sage X3 uses a GraphQL API. The documentation states that GraphQL was chosen as the technology for building APIs for Sage X3 because it offers more flexibility than other API architectures.

Sage Business Cloud Accounting uses a REST API. The documentation explicitly states "The Accounting API from Sage is a RESTful application programming interface (API)".

Sage X3 also has a legacy SOAP API. The documentation mentions "SOAP Connection Pools" for X3.

Does the Sage Business Cloud API have webhooks?

Webhooks Support

The official Sage Business Cloud API does support webhooks for certain products and services. However, the availability and implementation of webhooks vary across different Sage products.

Types of Events

The types of events you can subscribe to depend on the specific Sage product or service you're using. Here are some examples:

Sage People:
- Employee changes (creation, updates, deletion)
Sage Business Cloud Accounting:
- Polling events for various resources, including customers
Sage Banking Service:
- Notifications for banking-related events
Sage Payments Out Service:
- Provider-related notifications

Key Considerations

Configuration: For some services like Sage People, you need to set up Named Credentials and create a Webhook Object to receive updates.
Polling vs. Real-time: Some services use polling mechanisms instead of real-time webhooks. For example, Sage Business Cloud Accounting supports polling events.
Authentication: Webhooks often require authentication. For instance, the Payments Out Service uses Sage ID tokens and custom headers for security.
Event Types: The specific events available vary by product. For example, Sage People currently only provides webhooks for Employee changes.
Registration: Some services may require you to register your application to receive webhooks. For example, the Banking Service requires your applicationId to be registered with their Notification Service.

Best Practices

Secure your webhook endpoints using the provided authentication mechanisms.
Implement proper error handling and retry logic for webhook processing.
Consider the refresh interval for polling-based events to balance timely updates with API usage limits.
Familiarize yourself with the specific webhook or notification implementation for the Sage product you're integrating with, as they can vary significantly.

In conclusion, while Sage Business Cloud API does offer webhook functionality, the implementation and available events differ across their product line. It's important to consult the specific documentation for the Sage product you're working with to understand the exact capabilities and requirements for webhook integration.

Rate Limits and other limitations

Based on the search results, here are the key API rate limits for the Sage Business Cloud API:

Rate Limits

Rate limit of 1,296,000 requests per app per day
Maximum of 150 concurrent requests at any time (per app)
Limit of 100 requests per minute per company
Limit of 2,500 requests per day per company
Limit of 20 failed login attempts per hour through the API

Additional Limitations

Maximum 100MB of data transfer in any 60 minute period (per Sage Accounting business)

Key Points to Consider

If rate limits are exceeded, the API will return a HTTP 429 error response
IP addresses may be blocked for 1 hour if per-minute limits are exceeded
It's advisable to make no more than one request per second to avoid hitting limits
Accounts are automatically unblocked within an hour after being temporarily blocked
Some API calls are considered "heavier" and should be used sparingly to avoid performance issues

Best Practices

Implement wait and repeat functionality to handle 429 responses
Consider caching static or seldom updated data to reduce API calls
Queue requests if a limit is reached rather than continuing to make calls
Contact Sage Accounting developer support if you need to increase any limits

It's important to note that these limits may be subject to change, so it's always best to refer to the most up-to-date documentation or contact Sage directly for the latest information on API rate limits.

Latest API Version

Based on the search results provided, the most recent version of the Sage Business Cloud API is version 3.1. Here are the key points:

Current API Version

The most recent version of the Sage Business Cloud Accounting API is version 3.1 [2][3].

Key Points

API v3.1 is currently supported and being actively developed for Sage Business Cloud Accounting and Sage Business Cloud Start products [2].
API v3.1 was initially released in beta in October 2018 [3].
It officially left beta status in April 2019 [3].
API v3.1 is now available for use with Canadian businesses as well, in addition to other regions [3].

Compatibility and Support

For Sage Business Cloud Accounting and Start products, both API v3 and v3.1 are supported and under active development [2].
For UK and Ireland users, API v1 and v2 are also still supported, though users are encouraged to migrate to v3.1 [2].
For US users, only v2 is supported in addition to v3 and v3.1, with migration to v3.1 recommended [2].

Best Practices

Developers are encouraged to consider migrating to API v3.1 if they are using older versions [2].
The API documentation provides detailed guides and references for working with the latest version [4].

It's important to note that while v3.1 is the most recent version, Sage continues to support some older versions for certain regions and products. However, for the most up-to-date features and best long-term compatibility, developers should aim to use API v3.1 where possible.

How to get a Sage Business Cloud developer account and API Keys?

Here's how you can get a developer account for Sage Business Cloud to create an API integration:

Key steps:

Sign up for a Sage Developer Account
Set up a trial business for development
Register your application and get API credentials

Detailed process:

Go to the Sage developer portal (https://developer.sage.com)
Click "Sign Up" and create an account using your email address or GitHub account
This account allows you to register and manage your applications, obtain client credentials, and specify details like callback URLs

Set up a trial business for development:

Create trial businesses for the regions and subscription tiers of Sage Business Cloud Accounting you want to develop for
You can create multiple trial accounts to test different tiers and regions
Consider using email aliases to manage multiple trial accounts

Once logged into the developer portal, select "Create app" to register a new application
Provide details like app name, contact email, homepage URL, and callback URLs
For the callback URL, use: https://sageone.codat.io/oauth/callback
After saving, you'll receive a Client ID and Client Secret
Keep these credentials secure - you'll need them to authenticate API requests

What can you do with the Sage Business Cloud API?

Based on the search results provided, here is a list of data models that can be interacted with using the Sage Business Cloud Accounting API, along with what is possible for each:

Contacts

Create, read, update and delete contact information for customers and suppliers
Manage contact details like name, address, phone number, etc.

Sales Invoices

Create and manage sales invoices
Record payments against invoices
Apply credits and refunds

Purchase Invoices

Create and manage purchase invoices/bills
Record payments made to suppliers

Bank Accounts

View bank account information
Record bank transactions

Ledger Accounts

View and manage general ledger accounts
Post journal entries

Products & Services

Create and manage product/service catalog items
Update pricing and inventory information

Tax Rates

View and manage tax rates and tax codes

Payments

Record customer payments received
Make payments to suppliers

Journal Entries

Create manual journal entries
Post adjustments to the general ledger

Reporting

Generate financial reports like profit & loss, balance sheet
Run sales and purchase reports

Users

Manage user access and permissions

Key points to consider:

The API provides both read and write access to most data models
Authentication is required to access the API endpoints
Rate limits and usage quotas may apply
The API uses RESTful principles and returns data in JSON format

While the search results don't provide an exhaustive list, these appear to be the core data models exposed through the Sage Business Cloud Accounting API based on the available information. The API allows developers to integrate Sage's accounting functionality into their own applications and workflows.