Map transactions

Associate expense transactions with the correct accounts, tax rates, suppliers, and customers in your customer’s accounting software

Overview

Before creating expense transactions, you need to understand how to map your expense data to the correct accounts, tax rates, suppliers, and customers in your customer’s accounting software. This ensures expenses are categorized correctly and appear in the right place in their books.

Configuration levels

Sync2Books supports expense mapping at two levels:

Company-level defaults - Set default mappings that apply to all expenses for a company
Transaction-level overrides - Specify mappings for individual expense transactions

Company-level configuration

Set default mappings at the company level to ensure expenses are automatically categorized correctly even if specific references are omitted in individual transactions.

Configure expense defaults

Request

PATCH /companies/{companyId}/expense-config

{
  "bankAccount": {
    "id": "bank-account-id"
  },
  "supplier": {
    "id": "supplier-id"
  },
  "customer": {
    "id": "customer-id"
  },
  "defaultAccount": {
    "id": "expense-account-id"
  },
  "defaultTaxRate": {
    "id": "tax-rate-id"
  }
}

Response

{
  "companyId": "77921ff9-2491-4dfe-b23b-ff28f3e31e4f",
  "bankAccount": {
    "id": "41",
    "name": "Checking Account"
  },
  "supplier": {
    "id": "supplier-123",
    "name": "Default Supplier"
  },
  "defaultAccount": {
    "id": "64",
    "name": "Office Expenses"
  },
  "defaultTaxRate": {
    "id": "tax-10",
    "name": "Sales Tax 10%"
  }
}

Get expense configuration

Request

GET /companies/{companyId}/expense-config

Response

{
  "companyId": "77921ff9-2491-4dfe-b23b-ff28f3e31e4f",
  "bankAccount": {
    "id": "41",
    "name": "Checking Account"
  },
  "supplier": {
    "id": "supplier-123",
    "name": "Default Supplier"
  },
  "defaultAccount": {
    "id": "64",
    "name": "Office Expenses"
  },
  "defaultTaxRate": {
    "id": "tax-10",
    "name": "Sales Tax 10%"
  }
}

Transaction-level mapping

When creating an expense transaction, you can specify mappings for that specific transaction. These override company-level defaults.

Required mappings

accountRef - The expense account to categorize the expense
taxRateRef - The tax rate to apply (if applicable)

Optional mappings

contactRef - Supplier or customer associated with the expense
bankAccountRef - Bank account used for the payment
trackingRefs - Tracking categories for reporting
invoiceTo - Customer to invoice (for billable expenses)

Example expense with mappings

{
  "id": "expense-001",
  "type": "Payment",
  "issueDate": "2024-01-15T00:00:00Z",
  "currency": "USD",
  "currencyRate": 1,
  "merchantName": "Office Supplies Co",
  "contactRef": {
    "id": "supplier-id",
    "type": "Supplier"
  },
  "bankAccountRef": {
    "id": "bank-account-id"
  },
  "lines": [
    {
      "netAmount": 100.00,
      "taxAmount": 10.00,
      "taxRateRef": {
        "id": "tax-rate-id"
      },
      "accountRef": {
        "id": "expense-account-id"
      },
      "trackingRefs": [
        {
          "id": "tracking-category-id",
          "dataType": "trackingCategories"
        }
      ],
      "invoiceTo": {
        "id": "customer-id",
        "type": "Customer"
      }
    }
  ],
  "notes": "Office supplies for Q1 2024"
}

Getting reference IDs

Before creating expenses, you need valid IDs from your customer’s accounting system. You can retrieve these using Sync2Books reference endpoints.

Get accounts

Request

GET /connections/{connectionId}/accounts

Response

{
  "accounts": [
    {
      "id": "64",
      "name": "Office Expenses",
      "type": "Expense",
      "status": "Active"
    },
    {
      "id": "65",
      "name": "Travel Expenses",
      "type": "Expense",
      "status": "Active"
    }
  ]
}

Get tax rates

Request

GET /connections/{connectionId}/tax-rates

Response

{
  "taxRates": [
    {
      "id": "tax-10",
      "name": "Sales Tax 10%",
      "rate": 10.0,
      "status": "Active"
    }
  ]
}

Get suppliers

Request

GET /connections/{connectionId}/suppliers

Response

{
  "suppliers": [
    {
      "id": "supplier-123",
      "name": "Office Supplies Co",
      "status": "Active"
    }
  ]
}

Get customers

Request

GET /connections/{connectionId}/customers

Response

{
  "customers": [
    {
      "id": "customer-456",
      "name": "Acme Corp",
      "status": "Active"
    }
  ]
}

Fallback behavior

If a transaction omits a reference (e.g., contactRef or bankAccountRef), Sync2Books will:

Check for company-level defaults
Use the default if available
Return an error if required and no default is set

Example: Missing contact reference

If an expense transaction doesn’t include a contactRef:

Sync2Books checks for a company-level supplier default
If found, uses that supplier
If not found, checks for a company-level customer default
If still not found, the sync may fail (depending on accounting software requirements)

Best practices

Set company-level defaults - Configure defaults for common mappings to reduce transaction complexity
Validate reference IDs - Ensure all IDs exist in the accounting system before creating expenses
Use tracking categories - Leverage tracking categories for better reporting and categorization
Handle billable expenses - Use invoiceTo to mark expenses as billable to customers
Document mappings - Keep a record of your mapping strategy for each customer

Get started

Core concepts

Expenses

eTIMS compliance (Kenya)

Accounting integrations

Link component

Overview

Configuration levels

Company-level configuration

Configure expense defaults

Request

Response

Get expense configuration

Request

Response

Transaction-level mapping

Required mappings

Optional mappings

Example expense with mappings

Getting reference IDs

Get accounts

Request

Response

Get tax rates

Request

Response

Get suppliers

Request

Response

Get customers

Request

Response

Fallback behavior

Example: Missing contact reference

Best practices

Read next

​Overview

​Configuration levels

​Company-level configuration

​Configure expense defaults

​Request

​Response

​Get expense configuration

​Request

​Response

​Transaction-level mapping

​Required mappings

​Optional mappings

​Example expense with mappings

​Getting reference IDs

​Get accounts

​Request

​Response

​Get tax rates

​Request

​Response

​Get suppliers

​Request

​Response

​Get customers

​Request

​Response

​Fallback behavior

​Example: Missing contact reference

​Best practices

​Read next

Overview

Configuration levels

Company-level configuration

Configure expense defaults

Request

Response

Get expense configuration

Request

Response

Transaction-level mapping

Required mappings

Optional mappings

Example expense with mappings

Getting reference IDs

Get accounts

Request

Response

Get tax rates

Request

Response

Get suppliers

Request

Response

Get customers

Request

Response

Fallback behavior

Example: Missing contact reference

Best practices

Read next