Create Transactions

Create expense transactions and submit them for sync to your customer's accounting software

Overview

When you create an expense transaction, Sync2Books stores it in the database and queues it for sync to the connected accounting system. The actual synchronization happens asynchronously, allowing you to create multiple expenses efficiently.

Prerequisites

Before creating expenses, ensure you have:

✅ API Key - Your application's API key
✅ Connection ID - A connected accounting system (QuickBooks, Xero, or Sage)
✅ Account IDs - Valid account IDs from the accounting system
✅ Tax Rate IDs - Valid tax rate IDs (if applicable)

Create a single expense

Endpoint

POST /expenses/{connectionId}

Request Body

{
  "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",
  "postAsDraft": false
}

Field Descriptions

Field

Type

Required

Description

id

string

✅

Unique identifier for the expense (UUID format recommended)

type

string

✅

Expense type: "Payment" or "DirectCost"

issueDate

string (ISO 8601)

✅

Date when the expense was incurred

currency

string

✅

Three-letter currency code (e.g., "USD", "GBP")

currencyRate

number

✅

Exchange rate (usually 1 for base currency)

merchantName

string

✅

Name of the merchant/vendor

contactRef

object

❌

Reference to a supplier/customer

bankAccountRef

object

❌

Reference to the bank account used

lines

array

✅

Array of expense line items

notes

string

❌

Additional notes about the expense

postAsDraft

boolean

❌

If true, creates as draft in accounting system

Expense Lines

Each expense line item requires:

netAmount (number, required): Net amount before tax
taxAmount (number, required): Tax amount
taxRateRef (object, required): Reference to tax rate
accountRef (object, required): Reference to expense account

Optional fields:

trackingRefs (array): Tracking categories for reporting
invoiceTo (object): Customer to invoice (for billable expenses)

Example: Simple Expense

curl -X POST "https://api.sync2books.com/v1/expenses/{connectionId}" \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "exp-001",
    "type": "Payment",
    "issueDate": "2024-01-15T00:00:00Z",
    "currency": "USD",
    "currencyRate": 1,
    "merchantName": "Amazon",
    "lines": [
      {
        "netAmount": 50.00,
        "taxAmount": 5.00,
        "taxRateRef": { "id": "tax-10-percent" },
        "accountRef": { "id": "office-supplies-account" }
      }
    ]
  }'

Response

{
  "syncBatchId": "550e8400-e29b-41d4-a716-446655440000",
  "totalExpenses": 1
}

The syncBatchId is used to track the sync status. See Sync transactions for monitoring sync progress.

Create multiple expenses (batch)

You can create multiple expenses in a single request for better efficiency:

Request

curl -X POST "https://api.sync2books.com/v1/expenses/{connectionId}" \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": "exp-001",
      "type": "Payment",
      "issueDate": "2024-01-15T00:00:00Z",
      "currency": "USD",
      "currencyRate": 1,
      "merchantName": "Amazon",
      "lines": [
        {
          "netAmount": 50.00,
          "taxAmount": 5.00,
          "taxRateRef": { "id": "tax-10-percent" },
          "accountRef": { "id": "office-supplies-account" }
        }
      ]
    },
    {
      "id": "exp-002",
      "type": "Payment",
      "issueDate": "2024-01-16T00:00:00Z",
      "currency": "USD",
      "currencyRate": 1,
      "merchantName": "Staples",
      "lines": [
        {
          "netAmount": 75.00,
          "taxAmount": 7.50,
          "taxRateRef": { "id": "tax-10-percent" },
          "accountRef": { "id": "office-supplies-account" }
        }
      ]
    }
  ]'

Response

{
  "syncBatchId": "550e8400-e29b-41d4-a716-446655440000",
  "totalExpenses": 2
}

All expenses in the batch are processed together and share the same syncBatchId.

Transaction types

Payment

A standard expense payment. This is the most common transaction type.

{
  "type": "Payment",
  "issueDate": "2024-01-15T00:00:00Z",
  "merchantName": "Office Supplies Co",
  "lines": [...]
}

DirectCost

A direct cost expense, typically used for cost of goods sold (COGS).

{
  "type": "DirectCost",
  "issueDate": "2024-01-15T00:00:00Z",
  "merchantName": "Raw Materials Supplier",
  "lines": [...]
}

Expense line items

Basic line item

{
  "netAmount": 100.00,
  "taxAmount": 10.00,
  "taxRateRef": {
    "id": "tax-rate-id"
  },
  "accountRef": {
    "id": "expense-account-id"
  }
}

Line item with tracking

{
  "netAmount": 100.00,
  "taxAmount": 10.00,
  "taxRateRef": {
    "id": "tax-rate-id"
  },
  "accountRef": {
    "id": "expense-account-id"
  },
  "trackingRefs": [
    {
      "id": "tracking-category-id",
      "dataType": "trackingCategories"
    }
  ]
}

Billable expense line item

{
  "netAmount": 100.00,
  "taxAmount": 10.00,
  "taxRateRef": {
    "id": "tax-rate-id"
  },
  "accountRef": {
    "id": "expense-account-id"
  },
  "invoiceTo": {
    "id": "customer-id",
    "type": "Customer"
  }
}

Data model

Expense Entity

{
  id: string;                    // Unique identifier
  type: "Payment" | "DirectCost";
  issueDate: string;              // ISO 8601 date
  currency: string;               // Currency code
  currencyRate: number;
  merchantName: string;
  contactRef?: {
    id: string;
    type: "Supplier" | "Customer";
  };
  bankAccountRef?: {
    id: string;
  };
  lines: ExpenseLine[];
  notes?: string;
  postAsDraft?: boolean;
}

Expense Line

{
  netAmount: number;
  taxAmount: number;
  taxRateRef: {
    id: string;
  };
  accountRef: {
    id: string;
  };
  trackingRefs?: Array<{
    id: string;
    dataType: "trackingCategories";
  }>;
  invoiceTo?: {
    id: string;
    type: "Customer";
  };
}

Getting reference IDs

Before creating expenses, you need valid IDs from your accounting system. See Map transactions for details on retrieving account, tax rate, supplier, and customer IDs.

Error handling

Validation errors

If required fields are missing or invalid:

{
  "statusCode": 400,
  "message": ["id should not be empty", "currency must be a string"],
  "error": "Bad Request"
}

Invalid reference IDs

If a reference ID doesn't exist in the accounting system, the sync will fail. Check the sync batch status for error details.

Best practices

Use UUIDs for expense IDs - Ensures uniqueness across your system
Batch multiple expenses - More efficient than individual requests
Validate data before sending - Ensure all required fields are present
Use company-level defaults - Reduce transaction complexity by setting defaults
Handle errors gracefully - Implement retry logic for transient failures

Good night

Create Transactions

Overview

Prerequisites

Create a single expense

Endpoint

Request Body

Field Descriptions

Expense Lines

Example: Simple Expense

Response

Create multiple expenses (batch)

Request

Response

Transaction types

Payment

DirectCost

Expense line items

Basic line item

Line item with tracking

Billable expense line item

Data model

Expense Entity

Expense Line

Getting reference IDs

Error handling

Validation errors

Invalid reference IDs

Best practices

Read next

Good night

hashtagOverview

hashtagPrerequisites

hashtagCreate a single expense

hashtagEndpoint

hashtagRequest Body

hashtagField Descriptions

hashtagExpense Lines

hashtagExample: Simple Expense

hashtagResponse

hashtagCreate multiple expenses (batch)

hashtagRequest

hashtagResponse

hashtagTransaction types

hashtagPayment

hashtagDirectCost

hashtagExpense line items

hashtagBasic line item

hashtagLine item with tracking

hashtagBillable expense line item

hashtagData model

hashtagExpense Entity

hashtagExpense Line

hashtagGetting reference IDs

hashtagError handling

hashtagValidation errors

hashtagInvalid reference IDs

hashtagBest practices

hashtagRead next

Overview

Prerequisites

Create a single expense

Endpoint

Request Body

Field Descriptions

Expense Lines

Example: Simple Expense

Response

Create multiple expenses (batch)

Request

Response

Transaction types

Payment

DirectCost

Expense line items

Basic line item

Line item with tracking

Billable expense line item

Data model

Expense Entity

Expense Line

Getting reference IDs

Error handling

Validation errors

Invalid reference IDs

Best practices

Read next