← All articles

Create and adjust a general journal entry

General journal entries in Sage 50 are posted through the General Journals API. Use POST /api/general-journals to create a balanced entry, and PUT /api/general-journals/{journalId} to correct an existing entry in the current fiscal year.

Prerequisites

Before posting a general journal entry, make sure you have:

Authentication

Pass your API key in the x-api-key request header:

x-api-key: YOUR_API_KEY

Endpoints

POST /api/general-journals
PUT  /api/general-journals/{journalId}

Every entry must have at least two lines, and total debits must equal total credits. Use display account numbers from the chart of accounts, not internal accountId values.

What you actually need to send

You must send date, source, and at least two balanced lines. Header and line comments are optional.

Field Required? What happens if omitted
date Yes Request is rejected. The date must fall within the company’s open fiscal period
source Yes Sage rejects the entry. Use a reference such as "ADJ-001" or a numeric source
lines Yes Request is rejected. At least two lines are required
accountNumber Yes (per line) Use the display number from GET /api/general-accounts
debitAmount Yes (per line) Set to 0 on credit lines
creditAmount Yes (per line) Set to 0 on debit lines
comment No Header comment is optional
comment (line) No Line comment is optional
lineNumber No Assigned automatically from the order of items in lines
currencyCode No Sage uses the company home currency
exchangeRate No Required only when posting in a foreign currency

Total debits across all lines must equal total credits. Each line should carry either a debit or a credit, not both.

Look up account numbers with GET /api/general-accounts before posting. The examples below use accounts from a sample company (57400 Miscellaneous, 10600 Regal Bank Current). Your chart of accounts will differ.

Request body

Minimum example with two balanced lines. date, source, and the line amounts are required:

{
  "date": "2025-03-15T00:00:00",
  "source": "997",
  "lines": [
    {
      "accountNumber": 57400,
      "debitAmount": 1.0,
      "creditAmount": 0
    },
    {
      "accountNumber": 10600,
      "debitAmount": 0,
      "creditAmount": 1.0
    }
  ]
}

Full example with header fields and line comments:

{
  "date": "2025-03-15T00:00:00",
  "source": "ADJ-001",
  "comment": "Monthly accrual",
  "lines": [
    {
      "accountNumber": 57400,
      "debitAmount": 2.0,
      "creditAmount": 0,
      "comment": "Expense accrual"
    },
    {
      "accountNumber": 10600,
      "debitAmount": 0,
      "creditAmount": 2.0,
      "comment": "Offset to bank"
    }
  ]
}

For a foreign-currency journal, add currencyCode and exchangeRate to the header:

{
  "date": "2025-03-15T00:00:00",
  "source": "FX-001",
  "comment": "USD adjustment",
  "currencyCode": "USD",
  "exchangeRate": 1.35,
  "lines": [
    {
      "accountNumber": 57400,
      "debitAmount": 100.0,
      "creditAmount": 0
    },
    {
      "accountNumber": 10600,
      "debitAmount": 0,
      "creditAmount": 100.0
    }
  ]
}

cURL example

Create a general journal entry:

curl -X POST "/api/general-journals" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "date": "2025-03-15T00:00:00",
    "source": "ADJ-001",
    "comment": "Monthly accrual",
    "lines": [
      {
        "accountNumber": 57400,
        "debitAmount": 2.0,
        "creditAmount": 0,
        "comment": "Expense accrual"
      },
      {
        "accountNumber": 10600,
        "debitAmount": 0,
        "creditAmount": 2.0,
        "comment": "Offset to bank"
      }
    ]
  }'

Adjust an entry

A PUT does not change the original entry. Sage posts a new journal entry with the corrected amounts and returns a new id. The original entry stays as posted.

Send the full corrected header and lines in the request body. {journalId} is the id of the original entry from create or GET.

Adjust an existing entry in the current fiscal year:

curl -X PUT "/api/general-journals/541" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "date": "2025-03-15T00:00:00",
    "source": "996",
    "comment": "Corrected amount",
    "lines": [
      {
        "accountNumber": 57400,
        "debitAmount": 4.0,
        "creditAmount": 0,
        "comment": "Corrected debit"
      },
      {
        "accountNumber": 10600,
        "debitAmount": 0,
        "creditAmount": 4.0,
        "comment": "Corrected credit"
      }
    ]
  }'

Use the id from the create response as {journalId}. After a successful PUT, use the new id from the response, not the original {journalId}, to retrieve the correcting entry. The original entry is unchanged.

Success response

A successful create request returns 201 Created with the posted general journal entry:

{
  "id": 535,
  "isLastYear": false,
  "date": "2025-03-15T00:00:00",
  "source": "997",
  "comment": "",
  "debitTotal": 5.0,
  "creditTotal": 5.0,
  "lines": [
    {
      "lineNumber": 1,
      "accountNumber": 57400,
      "debitAmount": 5.0,
      "creditAmount": 0.0,
      "comment": "Line one note"
    },
    {
      "lineNumber": 2,
      "accountNumber": 10600,
      "debitAmount": 0.0,
      "creditAmount": 5.0,
      "comment": "Line two note"
    }
  ]
}

A successful adjust request returns 200 OK with the new correcting entry. The id is different from the {journalId} you sent in the URL:

{
  "id": 543,
  "isLastYear": false,
  "date": "2025-03-15T00:00:00",
  "source": "996",
  "comment": "Corrected amount",
  "debitTotal": 4.0,
  "creditTotal": 4.0,
  "lines": [
    {
      "lineNumber": 1,
      "accountNumber": 57400,
      "debitAmount": 4.0,
      "creditAmount": 0.0,
      "comment": "Corrected debit"
    },
    {
      "lineNumber": 2,
      "accountNumber": 10600,
      "debitAmount": 0.0,
      "creditAmount": 4.0,
      "comment": "Corrected credit"
    }
  ]
}

If you GET the original entry (541 in this example), it still shows the first posted amounts. GET the new id from the PUT response to read the correcting entry.

Error response

If the request is invalid or Sage rejects the entry, the API returns an error with a ProblemDetails body. Validation and Sage business rule failures commonly return 500 with a detail message:

{
  "title": "An error has occurred on the server",
  "status": 500,
  "detail": "Total debits must equal total credits.\r\nParameter name: dto",
  "code": "500",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Other common detail values include "Date is required.", "This transaction must have a source code.", a fiscal period range message when the date is out of range, "At least two journal lines are required.", and "General journal {id} could not be opened for adjustment." when a PUT adjust is not allowed.

Next steps