> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hotglue.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sage 200

# Connector Details

| Name | Value |
| :- | :- |
| Platform | [Sage 200](https://www.sage.com/en-gb/products/sage-200/) |
| Auth Type | OAuth |
| Direction | Write |
| Target Repo | [https://github.com/hotgluexyz/target-sage-200](https://github.com/hotgluexyz/target-sage-200) |
| Target Metrics | Usage: (low) |

# Overview

Sage 200 is a UK mid-market ERP for financials, inventory, and sales order processing. It is available as **Sage 200 Standard** and **Sage 200 Professional** (formerly Sage 200 Extra). It is a distinct product from [Sage 50 UK](https://docs.hotglue.com/connectors/sage-50.md), [Sage 100](https://docs.hotglue.com/connectors/sage-100.md), and [Sage 300](https://docs.hotglue.com/connectors/sage300.md).

The hotglue Sage 200 connector writes data through the [Sage 200 REST API](https://developer.sage.com/200-uk/). Read syncs are not supported.

hotglue supports both Sage 200 Standard and Sage 200 Professional. The two variants use different API roots — selecting the wrong one typically surfaces as "no sites found" during authorization rather than at request time.

# Credentials Setup

Follow the steps below to get the credentials you need to use the Sage 200 connector.

## 1. Request OAuth client credentials

Sage 200 uses Sage ID OAuth 2.0 (authorization code grant). Client credentials are not self-serve in a developer console.

1. Request **Confidential (web)** API credentials from [Sage Developer Support](https://developer.sage.com/200-uk/docs/latest/api/getting-started-with-the-api/prerequisites/prepare-credentials-request).
2. Ask for separate **development** and **production** credentials if you need both environments.
3. When requesting credentials, register the redirect URI `https://hotglue.xyz/callback`.
4. Sage returns a `client_id` and `client_secret` by email.

Add those values to the Sage 200 connector credentials in hotglue. Tenants then complete the Sage ID OAuth consent flow when they link the connector.

## 2. Ensure the tenant API is reachable

For on-premise Sage 200 Professional, the Native API must be published (typically via Microsoft Entra Application Proxy) and registered with Sage Business Services. Sage 200 Standard Online is already cloud-hosted.

A useful connectivity check after linking is a successful `GET /sites` response for the authenticated Sage ID. Each site entry includes the `site_id` and `company_id` values the connector needs.

## 3. Tenant connection fields

After OAuth, tenants (or your flow config) must provide:

| Field | Required | Description |
| :- | :- | :- |
| `site_id` | Yes | Sent as the `X-Site` header on every API call. Returned from `GET /sites`. |
| `company_id` | Yes | Sent as the `X-Company` header. Returned from `GET /sites` for each company on a site. |
| `is_professional` | No (`true`) | `true` for Sage 200 Professional, `false` for Sage 200 Standard. Defaults to Professional. |

Optional connector settings:

| Field | Required | Description |
| :- | :- | :- |
| `default_product_group` | No | Existing Sage product group **code** used when a product's group cannot be created via API. Product type (Stock / Service/Labour / Miscellaneous) is inherited from this group. |
| `default_nominal_code` | No | When set, adds a nominal analysis row to sales ledger invoices and credit notes. |
| `warehouse_id` | No | Warehouse id for product warehouse holdings. Defaults to the first warehouse flagged for sales trading. |
| `update_existing_records` | No (`false`) | When `true`, refresh scalar fields on customers/products that already exist in Sage. Off by default so Sage-side values are not overwritten. |
| `import_as_sales_orders` | No (`false`) | When `true`, emit SOP sales orders (with line items) instead of sales ledger invoices. |
| `import_credits_as_sales_returns` | No (`false`) | When `true`, emit SOP sales returns (with line items) instead of sales ledger credit notes. Independent of `import_as_sales_orders`. |

# Supported Objects

## Write

The Sage 200 connector supports writing the objects below. Records are processed in dependency order: product categories → products → customers → documents.

> [!NOTE]
>
> Sage has no native upsert endpoint. By default the connector looks up customers and products by their natural key and only creates missing records. Matched records are left unchanged unless `update_existing_records` is enabled. Documents skip create when a matching posted transaction or analysis code already exists.

### ProductCategories

Payload file: `ProductCategories.json`

Looks up an existing product group by `code`. Product groups generally cannot be created through the API on many sites; missing groups are skipped and products fall back to `default_product_group` when configured.

| Field | Required | Description |
| :- | :- | :- |
| `code` | Yes | Product group code in Sage |
| `description` | No | Defaults to `code` if omitted |

> [accordion] Sample payload
>
> ```json theme={null}
> [
>   {
>     "code": "MISC",
>     "description": "Miscellaneous"
>   }
> ]
> ```

### Products

Payload file: `Products.json`

Creates products under an existing product group. Product type is inherited from the product group in Sage and cannot be set on the product itself.

| Field | Required | Description |
| :- | :- | :- |
| `code` | Yes | Unique product code |
| `name` | Yes | Product name |
| `product_group` | Yes\* | Product group code. Must exist in Sage (or resolve via `default_product_group`) |
| `tax_code` | No | Sage tax code (e.g. `0`, `1`); resolved to a tax code id |

\*Required unless `default_product_group` is set and can resolve the group.

> [accordion] Sample payload
>
> ```json theme={null}
> [
>   {
>     "code": "599IphoneX",
>     "name": "599 iPhone X",
>     "product_group": "MISC",
>     "tax_code": "1"
>   }
> ]
> ```

### Customers

Payload file: `Customers.json`

| Field | Required | Description |
| :- | :- | :- |
| `reference` | Yes | Unique customer account reference |
| `name` | Yes | Customer name |
| `vat_number` | No | VAT registration number |
| `telephone` | No | Telephone subscriber number |
| `payment_term_days` | No | Payment terms in days |
| `payment_term_option` | No | `DAYS_AFTER_BILL_MONTH` maps to end-of-month terms; anything else uses document date |
| `contact_name` | No | Creates a default contact when set |
| `email` | No | Contact email (only sent when `contact_name` is set) |

> [accordion] Sample payload
>
> ```json theme={null}
> [
>   {
>     "reference": "599Fresh",
>     "name": "599 Freshodemo",
>     "contact_name": "Bruce Wayne",
>     "telephone": "(599) 456 7890",
>     "email": "demo@fresho.com",
>     "vat_number": "DE123456599",
>     "payment_term_days": 20,
>     "payment_term_option": "DAYS_AFTER_BILL_MONTH"
>   }
> ]
> ```

### Invoices / CreditNotes

Payload files: `Invoices.json` / `CreditNotes.json`

These post to the **sales ledger** (`/sales_invoices`, `/sales_credit_notes`). They are financial summaries (goods + tax totals) against the customer account — not printable SOP invoices with product lines. Posted documents appear under Transaction Enquiry.

There is no Sage 200 API for multi-line SOP invoices. Prefer `import_as_sales_orders` / `import_credits_as_sales_returns` when line-item detail must appear in Sage.

| Field | Required | Description |
| :- | :- | :- |
| `customer_reference` | Yes | Customer account reference (must already exist) |
| `order_number` | No | Mapped to ledger `reference` |
| `ref` | No | Mapped to ledger `second_reference` |
| `invoice_date` | No | Transaction date |
| `lines` | Yes | Line items collapsed into goods/tax totals |
| `lines[].quantity` | No | Used with `unit_price` when discounted totals are absent |
| `lines[].unit_price` | No | Unit price |
| `lines[].discounted_line_total` | No | Preferred goods total per line when present |
| `lines[].tax` | No | Tax amount for the line |

Ledger invoices/credit notes post to the customer account immediately. SOP orders/returns do not affect the ledger until processed in Sage.

> [accordion] Sample payload
>
> ```json theme={null}
> [
>   {
>     "customer_reference": "599Fresh",
>     "order_number": "F60185905",
>     "ref": "PO-123",
>     "invoice_date": "2026-10-21",
>     "lines": [
>       {
>         "product_code": "599IphoneX",
>         "quantity": 1,
>         "unit_price": 55.0,
>         "discounted_line_total": 55.0,
>         "tax": 5.5,
>         "tax_code": "1"
>       },
>       {
>         "product_code": "JSPCT",
>         "quantity": 1,
>         "unit_price": 25.0,
>         "discounted_line_total": 25.0,
>         "tax": 0,
>         "tax_code": "0"
>       }
>     ]
>   }
> ]
> ```

### SalesOrders / SalesReturns

Payload files: `SalesOrders.json` / `SalesReturns.json`

These post SOP documents (`/sop_orders`, `/sop_returns`) with real product lines. Both endpoints take the same body; direction is determined by the document type, not the sign of quantities.

| Field | Required | Description |
| :- | :- | :- |
| `customer_reference` | Yes | Customer account reference (must already exist) |
| `order_number` | No | Sent as SOP `analysis_code_1` |
| `ref` | No | Sent as `customer_document_no` and SOP `analysis_code_2` |
| `invoice_date` | No | Document date |
| `lines` | Yes | Product lines |
| `lines[].product_code` | Yes | Product code (must already exist) |
| `lines[].quantity` | No | Line quantity |
| `lines[].unit_price` | No | Selling unit price |
| `lines[].discount_percent` | No | Unit discount percent |
| `lines[].tax_code` | No | Sage tax code for the line |
| `lines[].description` | No | Used in error messages only |

> [!TIP]
>
> In Sage, rename SOP analysis codes 1 and 2 to labels such as **F number** and **PO number** (Accounting System Manager → Maintain Analysis Codes; enable free text / amendment on SOP Settings → Invoice and Order Entry) so those values are readable on the document. They do not populate Transaction Enquiry Reference / 2nd Ref.

> [!WARNING]
>
> Posting SOP lines with a selling unit price requires the Sage API user to have **Override prices and discounts on order lines** enabled: Sales Order Processing → SOP Utilities → System Setup → User Permissions → select the user → Edit → enable the permission → Save.

> [accordion] Sample payload
>
> ```json theme={null}
> [
>   {
>     "customer_reference": "599Fresh",
>     "order_number": "F60185905",
>     "ref": "PO-123",
>     "invoice_date": "2026-10-21",
>     "lines": [
>       {
>         "product_code": "599IphoneX",
>         "description": "599 iPhone X",
>         "quantity": 1,
>         "unit_price": 55.0,
>         "discount_percent": 0,
>         "tax_code": "1"
>       }
>     ]
>   }
> ]
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.