Revenue and Expense

What you can retrieve

Retrieve the revenue and expense records of your own business in Bolta, in the same units as the revenue and expense lists in the dashboard. Each API key covers the one business it belongs to. You can also ask Bolta to collect sooner.

Path	Purpose
`GET /v1/revenues`	Revenue changes (cursor based)
`GET /v1/expenses`	Expense changes (cursor based)
`POST /v1/revenues:sync`	Request a revenue sync
`POST /v1/expenses:sync`	Request an expense sync

Responses carry tax invoices and invoices (type is HOMETAX_TAX_INVOICE). They include both documents issued through Bolta and documents collected from Hometax. Cash receipts are not included, even those issued through Bolta.

Requirements

These calls deduct no points. Instead, you need a Standard plan or higher. A free trial also qualifies when the trial plan is Standard or higher. When your plan does not qualify, all four paths return 402 with PLAN_UPGRADE_REQUIRED. Upgrade your plan from the billing menu in the Bolta dashboard, then call again.

Connect Hometax revenue and expense collection in the Bolta dashboard first.

A business that only issues through Bolta without connecting Hometax can still retrieve the tax invoices it issued as revenue. After you disconnect, the records already stored remain available. None of the four paths needs issuer registration, a certificate, or Bolta-Client-Reference-Id. Send Basic {apiKey} in the Authorization header. See the authentication guide.

Key limits

Item	Limit
Sync request	Once every 30 minutes and 12 times in 24 hours per business, counted separately for revenue and expense
Visibility	About 5 minutes after the change in Bolta
Hometax documents	Usually 1 to 2 hours after collection
Items per call (`limit`)	Up to 200. Defaults to 100

Revenue and expense lists

Both paths take the same parameters and return the same shape. The path decides whether an item is revenue or expense.

curl "https://xapi.bolta.io/v1/revenues?limit=100" \
  -H "Authorization: Basic {apiKey}"

Parameter	Required	Description
`from`	No	Start of the transaction date range. `YYYY-MM-DD` (KST, inclusive). For tax invoices, the write date
`to`	No	End of the transaction date range. `YYYY-MM-DD` (KST, inclusive)
`type`	No	`HOMETAX_TAX_INVOICE`
`cursor`	No	`nextCursor` from the previous response
`limit`	No	1 to 200. Defaults to 100

Without a date range, the API returns every stored record. The example below is the test key’s revenue response without a cursor, with 102 and 103 omitted.

{
  "items": [
    {
      "status": "ACTIVE",
      "id": "101",
      "type": "HOMETAX_TAX_INVOICE",
      "taxInvoice": {
        "ntsTransactionId": "20260901-10000000-00000101",
        "invoiceType": "TAX_INVOICE",
        "purpose": "CLAIM",
        "writtenDate": "2026-09-01",
        "issuedAt": "2026-09-01T05:12:00Z",
        "supplier": {
          "identificationNumberType": "BUSINESS",
          "identificationNumber": "1234567890",
          "taxRegistrationId": null,
          "organizationName": "주식회사 볼타테스트",
          "representativeName": "정대표",
          "address": "서울특별시 테스트구 테스트로 1",
          "businessType": "서비스",
          "businessItem": "소프트웨어 개발",
          "manager": {
            "name": "홍길동",
            "email": "tax@example.com",
            "telephone": "02-0000-0000"
          }
        },
        "supplied": {
          "identificationNumberType": "BUSINESS",
          "identificationNumber": "1111111111",
          "taxRegistrationId": null,
          "organizationName": "주식회사 테스트고객",
          "representativeName": "테스트대표",
          "address": "경기도 테스트시 샘플로 2",
          "businessType": "도매",
          "businessItem": "도소매",
          "manager": {
            "name": "김담당",
            "email": "buyer@example.com",
            "telephone": null
          }
        },
        "trustee": null,
        "totalSupplyCost": 1000000,
        "totalTax": 100000,
        "totalAmount": 1100000,
        "paymentMeans": {
          "cash": null,
          "check": null,
          "bankBill": null,
          "accountReceivable": 1100000
        },
        "description": null,
        "amendReason": null,
        "importDeclaration": null,
        "items": [
          {
            "date": "2026-09-01",
            "name": "컨설팅",
            "specification": null,
            "quantity": 1,
            "unitPrice": 600000,
            "supplyCost": 600000,
            "tax": 60000,
            "description": null
          },
          {
            "date": "2026-09-01",
            "name": "교육",
            "specification": null,
            "quantity": 2,
            "unitPrice": 200000,
            "supplyCost": 400000,
            "tax": 40000,
            "description": null
          }
        ]
      }
    },
    {
      "status": "REMOVED",
      "id": "104"
    }
  ],
  "nextCursor": "djI6MTc4ODU3MzYwMDAwMDAwMDoxMDQ6MXVpMmNn",
  "hasMore": false
}

The item shape depends on status.

`status`	Meaning	Fields
`ACTIVE`	A record visible in the Bolta dashboard	`status`, `id`, `type`, and the object that matches `type`
`REMOVED`	A record hidden from the dashboard because it was archived or deactivated	`status`, `id`

Field	Type	Description
`items[].status`	string	`ACTIVE`, `REMOVED`
`items[].id`	string	Revenue or expense identifier. Unique within the path
`items[].type`	string	Evidence type. `HOMETAX_TAX_INVOICE`
`items[].taxInvoice`	object	The tax invoice when `type` is `HOMETAX_TAX_INVOICE`
`nextCursor`	string	Cursor to pass on the next call
`hasMore`	boolean	Whether more items are available right now

id identifies one revenue or expense record, not the tax invoice. HOMETAX_TAX_INVOICE means a tax invoice or invoice registered with the National Tax Service (NTS). Documents issued through Bolta use the same value.

Tax invoice

taxInvoice has the same shape for revenue and expense.

Field	Type	Description
`ntsTransactionId`	string	NTS approval number
`invoiceType`	string	NTS document type. See Document types
`purpose`	string or null	`RECEIPT` or `CLAIM`
`writtenDate`	string	Write date `YYYY-MM-DD` (KST)
`issuedAt`	string	Issuance time (UTC). For documents whose details cannot be filled, 00:00 (KST) on the issuance date
`supplier`	object	Supplier. See Parties
`supplied`	object	Recipient
`trustee`	object or null	Trustee. Only on brokered documents
`totalSupplyCost`	integer	Total supply cost
`totalTax`	integer or null	Total tax. `null` for documents without tax, such as invoices
`totalAmount`	integer	Total amount
`paymentMeans.cash`	integer or null	Cash
`paymentMeans.check`	integer or null	Check
`paymentMeans.bankBill`	integer or null	Promissory note
`paymentMeans.accountReceivable`	integer or null	Accounts receivable
`description`	string or null	Remarks
`amendReason`	string or null	NTS amendment reason. See Amendment reasons. `null` unless the document is an amended tax invoice
`importDeclaration`	object or null	Import declaration. Only on import tax invoices
`importDeclaration.declarationNumber`	string or null	Import declaration number
`importDeclaration.periodStartDate`	string or null	Start of the taxable period (KST)
`importDeclaration.periodEndDate`	string or null	End of the taxable period (KST)
`importDeclaration.itemCount`	integer or null	Number of imports
`items`	array	Line items. Empty for documents whose details cannot be filled
`items[].date`	string or null	Item supply date (KST)
`items[].name`	string or null	Item name
`items[].specification`	string or null	Specification
`items[].quantity`	number or null	Quantity
`items[].unitPrice`	number or null	Unit price
`items[].supplyCost`	integer	Supply cost
`items[].tax`	integer or null	Tax
`items[].description`	string or null	Remarks

Amounts are integers in KRW and can be negative on amended tax invoices. Quantity and unit price come without a decimal point when they are whole numbers, and with their decimal places otherwise.

Parties

supplier, supplied, and trustee share the same shape.

Field	Type	Description
`identificationNumberType`	string	`BUSINESS`, `RESIDENT` (individual), or `FOREIGN` (foreigner)
`identificationNumber`	string	Identification number without hyphens
`taxRegistrationId`	string or null	Sub-business place code
`organizationName`	string or null	Company name
`representativeName`	string or null	Representative
`address`	string or null	Address
`businessType`	string or null	Business type
`businessItem`	string or null	Business item
`manager`	object or null	Manager. `null` when name, email, and phone are all missing
`manager.name`	string or null	Name
`manager.email`	string or null	Email
`manager.telephone`	string or null	Phone number

`identificationNumberType`	`identificationNumber`
`BUSINESS`	10-digit business registration number
`RESIDENT`	13-digit resident registration number
`FOREIGN`	Foreigner identification number

The supplier and trustee are always BUSINESS. Only the recipient can be RESIDENT or FOREIGN, and then taxRegistrationId, businessType, and businessItem are null. When the recipient has two managers, manager holds the first.

For RESIDENT, identificationNumber is the raw resident registration number. Encrypt it at rest and keep it out of your logs.

Document types

`invoiceType`	Document
`TAX_INVOICE`	Electronic tax invoice
`ZERO_RATED_TAX_INVOICE`	Zero-rate electronic tax invoice
`INVOICE`	Electronic tax-exemption invoice
`IMPORT_TAX_INVOICE`	Import electronic tax invoice (including deferred payment)

Brokered documents have no separate type. A document is a brokered document when trustee is set.

Amendment reasons

`amendReason`	Reason
`MISSPELLED`	Correction of Error in Entries
`CHANGE_SUPPLY_COST`	Change in Supply Cost
`RETURNED`	Return of Goods
`TERMINATION`	Cancellation of Contract
`LOCAL_LETTER_OF_CREDIT`	Local Letter of Credit Opened after Supply
`DOUBLE_ISSUANCE`	Double Issuance by Mistake

Correction of Error in Entries and Local Letter of Credit Opened after Supply amendments are issued as a pair: a cancelling document and a corrected document. The API sends both with the same reason.

Documents in the response

The API does not return documents whose details are still being filled. For documents collected from Hometax, Bolta receives the approval number, parties, and amounts first, and fills the issuance time, addresses, business types, managers, and line items later. Tax invoices issued through Bolta appear right away. Documents collected from Hometax appear after their details are filled, newest write date first, so with many past documents the older ones keep arriving later. When the detail lookup fails for good, the API sends the document with list values only and an empty items. Addresses, business types, business items, and managers can also be null. If the details are filled later, the document arrives again with the same id. ntsTransactionId, issuedAt, and invoiceType are always set. Management data that exists only in Bolta, such as payment status, memos, labels, and assignees, is not included.

Order and cursor

The API returns records in the order they changed in Bolta, not by write date or collection order. Follow this order so you do not miss past-dated documents, detail updates, archiving, or unarchiving that happen later. To show records by write date, sort by writtenDate after you receive them. The same id can arrive more than once. Apply items by id in the order you receive them.

ACTIVE: Overwrite the item with the same id, or add it if none exists.
REMOVED: Delete the item with the same id, or ignore it if none exists.

An expense also moves back in the order when Bolta re-evaluates its payment status, so the same expense can arrive again with identical content. Overwrite it.

Collection steps

Call without a cursor, then keep calling with nextCursor until hasMore is false.
Save the last nextCursor. The API fills nextCursor even when hasMore is false. Save separate cursors for revenue, expense, and each set of filters.
On your next collection, call with the saved cursor. You receive only the records that changed since then.

hasMore can be true even when items is empty. Decide whether to continue from hasMore, not from items.

Send the cursor exactly as received. When the path, filters, or key mode differ from when the cursor was issued, the API returns 400 with INVALID_CURSOR. A cursor issued with type and one issued without it count as different filters. After you change the filters or move from a test key to a live key, start over without a cursor. You can change limit on any page.

Handling new values

Bolta can add new type values, new fields, and new invoiceType or amendReason values without notice. New evidence types such as cash receipts arrive on the same paths with a new type and a matching object.

Skip items with an unknown type and keep processing.
Ignore unknown fields.
Keep processing when you receive an unknown enum value.

REMOVED arrives without type, so apply it by id as usual.

Sync request

Bolta collects revenue and expense records periodically, and starts the first collection as soon as you connect in the dashboard. Request a sync only when you need a document just registered with the NTS.

curl -X POST https://xapi.bolta.io/v1/revenues:sync \
  -H "Authorization: Basic {apiKey}"

{
  "acceptedAt": "2026-09-18T03:00:00Z",
  "nextAvailableAt": "2026-09-18T03:30:00Z"
}

Path	Collects
`POST /v1/revenues:sync`	All revenue connected in the dashboard
`POST /v1/expenses:sync`	All expenses connected in the dashboard

The API only accepts the request with 202 Accepted, and the collection runs asynchronously. There is no path to check collection status. Instead of waiting for it to finish, continue fetching the list with your saved cursor. See Key limits for the request limits. Requests rejected with 409 or 422 do not count toward the limit. nextAvailableAt reflects only the 30-minute interval, not the 24-hour count.

Status code	Error code	Meaning
`202`	-	Accepted
`409`	`SYNC_IN_PROGRESS`	A collection for the same path is already running, including Bolta’s regular collection. Request again after it ends
`422`	`NO_SOURCE_CONNECTED`	No revenue or expense connection in the dashboard
`429`	`SYNC_RATE_LIMITED`	Request limit exceeded. Wait for the `Retry-After` seconds
`503`	`SYNC_UNAVAILABLE`	Temporarily unable to evaluate the request. Request again shortly

Test key

Test keys return fixed samples regardless of your subscription, without the 5-minute delay. Sync requests do not collect anything, only return an accepted response, and use no quota. The sample’s own business is 주식회사 볼타테스트 (1234567890). Revenue (GET /v1/revenues)

`id`	Changed at (UTC)	Write date	`invoiceType`	Recipient	Total	Status
`101`	2026-09-01T05:12:30Z	2026-09-01	`TAX_INVOICE`	주식회사 테스트고객	1,100,000	`ACTIVE`
`102`	2026-09-04T00:00:00Z	2026-09-03	`ZERO_RATED_TAX_INVOICE`	테스트수출 주식회사	500,000	`ACTIVE`
`103`	2026-09-05T02:00:00Z	2026-09-05	`TAX_INVOICE`	주식회사 테스트고객	-220,000	`ACTIVE`
`104`	2026-09-05T02:00:00Z	2026-09-02				`REMOVED`

101: Tax invoice issued through Bolta, with two line items
102: Zero-rate tax invoice collected from Hometax
103: Change in Supply Cost amendment (amendReason is CHANGE_SUPPLY_COST). Negative amounts, and quantity and unitPrice are null on the line item
104: Revenue archived in the dashboard. It changed at the same time as 103 and comes after it by id

Expense (GET /v1/expenses)

`id`	Changed at (UTC)	Write date	`invoiceType`	Supplier	Total	Status
`201`	2026-09-01T09:00:00Z	2026-09-01	`TAX_INVOICE`	주식회사 테스트공급	110,000	`ACTIVE`
`202`	2026-09-03T00:00:00Z	2026-09-02	`INVOICE`	테스트농산	180,000	`ACTIVE`
`203`	2026-09-06T00:30:00Z	2026-09-05	`TAX_INVOICE`	주식회사 테스트물류	330,000	`ACTIVE`

201: Tax invoice collected from Hometax
202: Tax-exemption invoice. totalTax and the line item tax are null
203: Tax invoice whose details cannot be filled. Address, business type, business item, and manager are null, and items is empty

Call with limit=2 to see cursor paging across two pages. Date filters and cursors follow the same rules as with a live key.

Errors

Status code	Error code	Condition
`400`	`INVALID_REQUEST`	Invalid date format, `from` later than `to`, or an invalid `type` or `limit`
`400`	`INVALID_CURSOR`	Modified or malformed cursor, or the path, filters, or key mode differ from when the cursor was issued
`401`	-	API key authentication failed. Empty response body
`402`	`PLAN_UPGRADE_REQUIRED`	Plan below Standard
`409`	`SYNC_IN_PROGRESS`	A collection for the same path is already running
`422`	`NO_SOURCE_CONNECTED`	No revenue or expense connection
`429`	`SYNC_RATE_LIMITED`	Sync request limit exceeded. Comes with a `Retry-After` header
`500`	`INTERNAL_SERVER_ERROR`	Internal server error
`503`	`FEED_UNAVAILABLE`	Temporarily unable to load records. The cursor did not advance, so call again with the same cursor
`503`	`SYNC_UNAVAILABLE`	Temporarily unable to evaluate the sync request
`503`	`SERVICE_UNAVAILABLE`	Temporary internal API communication error

See Error codes for the full list.

API Introduction

API Guides

Use Cases

SDK / No-code

What you can retrieve

Requirements

Key limits

Revenue and expense lists

Tax invoice

Parties

Document types

Amendment reasons

Documents in the response

Order and cursor

Collection steps

Handling new values

Sync request

Test key

Errors

​What you can retrieve

​Requirements

​Key limits

​Revenue and expense lists

​Tax invoice

​Parties

​Document types

​Amendment reasons

​Documents in the response

​Order and cursor

​Collection steps

​Handling new values

​Sync request

​Test key

​Errors

​Related documents

What you can retrieve

Requirements

Key limits

Revenue and expense lists

Tax invoice

Parties

Document types

Amendment reasons

Documents in the response

Order and cursor

Collection steps

Handling new values

Sync request

Test key

Errors

Related documents