Sage One Accounting¶

Overview¶

The Sage One Accounting task integrates BaseCloud CRM with Sage One (Sage Business Cloud Accounting), enabling automated creation and retrieval of quotes, tax invoices, and customer records in your Sage accounting system.

Key Features:

• 6 Actions: Create quotes/invoices, manage customers, fetch documents
• Basic Authentication: Username/password + company ID
• Document Number Management: Manual control with automatic sequence reset
• Item-Based Line Items: Links to Sage inventory items
• Tax Type Support: Configurable tax rates per line item
• South African Focus: Optimized for ZAR and SA tax regulations

Use Cases:

• Sync CRM deals to Sage quotes and invoices
• Automated customer creation from CRM contacts
• Invoice generation on service completion
• Quote workflows with Sage document management
• Item-based billing with Sage inventory tracking

Prerequisites¶

1. Sage One Account¶

• Active Sage One subscription (South Africa)
• Account with API access enabled
• Username and password for authentication
• Company ID (available in Sage account settings)

2. Sage API access¶

BaseCloud calls Sage with its own Sage API key, so there is nothing to register. The task signs in with the Username, Password and Company ID set on it.

3. Sage Inventory Setup¶

For Invoice/Quote Creation:

• Items must exist in Sage inventory with item codes
• Note exact item codes for use in line items
• Configure tax types in Sage (note numeric IDs)

4. Customer Records¶

For Invoice Creation:

• Customers must exist in Sage with customer IDs
• Use find_customer or create_customer actions first
• Note customer IDs for quote/invoice creation

Tax: whether the unit prices you send include tax is the task's own Tax Inclusive setting, sent to Sage with the document. (The account's own "Invoice prices are" setting in Settings › General applies to BaseCloud's quotes and invoices, not to Sage.)

Outputs¶

Which fields appear depends on the action. Customer and invoice lookups populate their own groups.

Reference fields as {{task_<ID>_<field>}}.

Always emitted¶

Configuration¶

Builder fields¶

The Field column is the label as it appears in the task builder; Key is the name the value is stored under and referenced by.

Actions¶

Every action needs Username, Password and Company ID — the task fails at once without any of them, and without an action.

Create Quote and Create Tax Invoice¶

Both build the same document from the same settings; a quote takes an Expiry Date, a tax invoice a Due Date (both DD/MM/YYYY HH:mm). The document is dated today. An empty or past expiry or due date becomes today.

• Customer ID — the Sage customer's ID (Find Customer gives it).
• Document Number and Customer Reference — written onto the document as given.
• Tax Inclusive — Yes when the unit prices include tax.
• Line items, as lists separated by |, one entry per line: Item Code(s) (each must exist in Sage's items), Tax Type ID(s), Item Description(s), Item Quantity(ies), Unit Price(s), and optionally Item Comments. Every list must have the same number of entries, or the task fails with "Sage line items length mismatch." A Comments list of a different length is ignored — every line's comment is left empty. To carry the details shown under an item in BaseCloud, map item_details into Item Comments: it always has one entry per line.

The task reads Sage's current document numbering first and puts it back afterwards, so writing your own Document Number does not move Sage's own sequence on. Sage's created document is in response.

Failures name their cause: "Failed to get current document number." (Sage refused the credentials or the company), "Failed to get Item Code …" (no such item in Sage), "Sage line items length mismatch.", and "Failed to create quote." / "Failed to create invoice." (Sage rejected the document).

Create Customer¶

Creates a Sage customer from Customer Name and Customer Email. Sage's created customer is in response. It does not check for an existing customer first — use Find Customer for that.

Find Customer¶

Looks for a customer whose name is exactly Customer Name. Found: customer_matched is true, with customer_matched_id, customer_matched_name and customer_matched_email. Not found is not a failure: the task completes with "No customer found." and customer_matched false.

Fetch Quote and Fetch Tax Invoice¶

Find one quote (Quote ID) or tax invoice (Invoice ID) — matched against the document's document number in Sage, so give the number shown on the document. Found: invoice_matched is true and invoice holds the document. Not found is not a failure: the task completes saying so, with invoice_matched false.

Real-World Examples¶

Raise an invoice when a deal is won¶

CRM Trigger  (status changed to "Won")
  └─ Match to Client   look the client up
      └─ Sage          create a tax invoice for {{task_15001_match_client_name}}

Store the Sage customer ID on the client as a custom field so this step can map it straight in.

Create the Sage customer the first time you invoice them¶

CRM Trigger
  └─ Sage              find the customer by name
      └─ If Statement  {{task_21001_customer_matched}} is false
          └─ Sage      create the customer

customer_matched, customer_matched_id and customer_matched_name tell you whether the customer already exists, so you only create when you need to.

Email the invoice once Sage has it¶

Form Submission
  └─ Sage      create the invoice
      └─ Email  confirm to the client

Troubleshooting¶

Error: "Failed to get current document number"¶

Cause: Cannot retrieve document number sequence from Sage API

Solutions:

1. Verify credentials (Username, Password, Company ID) are correct

2. Check Sage API access is enabled for account

3. Sign in to Sage One with the same username and password to check them

4. Contact Sage support if API access issues persist

Error: "Failed to get Item Code {code}"¶

Cause: Item code doesn't exist in Sage inventory

Solutions:

1. Verify item code exists: Log into Sage → Inventory → Items → Search for code

2. Check exact spelling, and that no spaces crept in around the | separators

3. Create missing items in Sage first

Error: "Sage line items length mismatch"¶

Cause: Pipe-delimited arrays have different numbers of items

Solutions:

1. Count pipes in each field - must be equal:

Item Code: "A|B|C"        // 3 items
Item Quantity: "1|2|3"    // 3 items
Item Unit Price: "10|20"  // 2 items ✗ MISMATCH

1. Exception: Item Comments may differ in length — then every line's comment is left empty

2. Build every line-item list from the same source so the lists stay the same length

Error: "Failed to create quote/invoice"¶

Cause: Sage API rejected document creation

Solutions:

1. The run's message (run_text) carries the failure

2. Common issues:

3. Customer ID doesn't exist (use find_customer first)
4. Tax Type ID invalid (check Sage tax type configuration)
5. Document number already exists (use unique numbers)
6. Date format incorrect (must be DD/MM/YYYY HH:mm)
7. Negative quantities or prices

8. Validate all required fields are populated

9. Test with minimal invoice (1 line item) first

10. Ensure Tax Inclusive matches price format (inclusive vs exclusive)

Customer Not Found with find_customer¶

Cause: Exact name match not found in Sage

Solutions:

1. Check for typos or extra spaces in customer name

2. Sage search is exact match - "Acme Corp" ≠ "Acme Corporation"

3. Use standardized naming in CRM to match Sage

4. Create the customer when none is found: an If on {{task_21001_customer_matched}} equals false → Create Customer

Document Number Sequence Issues¶

Cause: Manual document number conflicts with Sage auto-increment

Solutions:

1. Use unique prefixes for CRM-generated documents:
2. CRM quotes: CRM-QU-001
3. CRM invoices: CRM-INV-001

4. Sage internal: QU001, INV001

5. The task puts Sage's own numbering back after writing your number, so Sage's sequence is not moved on by it

Authentication Failures¶

Cause: Invalid Basic Auth credentials

Solutions:

1. Verify Username and Password are correct (test in Sage web UI)

2. Check Company ID is numeric and correct

3. Check the Sage account has API access enabled

Tax Type ID Confusion¶

Cause: Incorrect or unknown tax type IDs

Solutions:

1. Tax Type IDs are numeric (e.g., 1, 2, 3) and company-specific

2. Find your company's tax type IDs in Sage, or ask Sage support for the IDs its API uses

Best Practices¶

• Use a dedicated Sage user for the task's Username and Password, with only the access it needs.
• Find before you create: run Find Customer first and create the customer only when customer_matched is false — Create Customer does not check for duplicates.
• Keep item codes identical in your quotes and in Sage's items; a code Sage does not have fails the task.
• Build every line-item list from the same source so they stay the same length.
• Fill Customer Reference with something that ties the document back to the CRM, such as the client's name or a deal number.
• Use a Delay between Sage tasks in a loop to stay clear of Sage's rate limits; a rate-limited call is retried later on its own.

FAQ¶

Q: Can I edit or delete Sage quotes and invoices from BaseCloud?

A: No — the task creates and fetches them. Edit or void them in Sage.

Q: Where do I find Tax Type IDs?

A: They belong to your Sage company. Find them in Sage, or ask Sage support for the IDs its API uses.

Q: How do I check an invoice later?

A: Fetch Tax Invoice with its document number; invoice holds what Sage has for it.

Q: Why did a run fail?

A: The run's message (run_text) says which step failed — see Troubleshooting above for each message.

Related Tasks¶

• BaseCloud Accounting - Internal alternative to Sage
• Xero - Alternative accounting integration
• Email - Send invoice notifications
• Loop - Bulk invoice creation
• If Statement - Handle customer creation logic
• Workflow Note - Log Sage actions
• Timer Trigger - Schedule recurring billing
• CRM Trigger - Trigger on deal/client changes

Technical Details¶

• Type ID: 21
• Function: taskSage() in automationService.js
• API: Sage One Accounting API v2.0.0
• Authentication: HTTP Basic Auth (Username:Password)
• Base URL: https://accounting.sageone.co.za/api/2.0.0/
• Outputs: {{task_<ID>_<field>}}, the ID being the task's own
• Geographic Focus: South Africa (ZAR, VAT compliance)