---
title: "Push a batch of invoice / credit-memo records from Boomi"
method: POST
path: "/v2/integrations/providers/boomi/invoices"
tags: ["integrations"]
---

# Push a batch of invoice / credit-memo records from Boomi

`POST /v2/integrations/providers/boomi/invoices`

## Request

- Base URL: `https://api.stuut.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.stuut.ai/v2/integrations/providers/boomi/invoices`
- Auth: HTTP bearer

Documents with `debit_credit_indicator == "H"` are routed to the
CreditMemo model; "S" lands as an Invoice. Max 100 per request.

## Request body

- BoomiInvoicePayload[]
  - `document_number` string, required: BKPF-BELNR (payment doc for DZ, invoice doc for RX) or VBRK-VBELN. Maps to Invoice.remote_id / CreditMemo.remote_id / Payment.remote_id depending on the row's routing.
  - `document_type` string, nullable: BKPF-BLART. Routes the row: 'DZ' = customer payment posting; 'DG' = credit memo; 'DR' / 'RX' = invoice.
  - `invoice_doc_type` string, nullable: VBRK-FKART
  - `fiscal_year` string, nullable: BKPF-GJAHR
  - `company_code` string, required: BKPF-BUKRS. Tenant routing is done via the inbound Bearer key, not by this field — but Stuut stores it as a custom field for audit and downstream filtering.
  - `customer_code` string, required: BSEG-KUNNR / VBRK-KUNRG (payer)
  - `document_date` string, date, required: VBRK-FKDAT or BKPF-BLDAT; maps to Invoice.issued_at
  - `posting_date` string, date, nullable: BKPF-BUDAT
  - `net_due_date` string, date, nullable: Derived from BSEG-ZTERM + ZFBDT. Required for invoices (SHKZG=S); omitted on payment postings (document_type=DZ etc.) which have no due date.
  - `currency` string, required: BKPF-WAERS; ISO 4217
  - `amount_in_document_currency` union, required: BSEG-WRBTR in the invoice's currency, expressed as a decimal in the standard/major unit (e.g. '120.44' for USD $120.44, '1250' for JPY ¥1,250). Accepts JSON string or number; string form is safest for precision. Stuut converts to the DB's smallest-unit storage using the currency's precision (USD → x100, JPY → x1, BHD → x1000).
    - number
    - string, decimal
  - `amount_in_local_currency` union: BSEG-DMBTR in the local (company code) currency, same decimal format
    - number
    - string, decimal
  - `exchange_rate` string, nullable: BKPF-KURSF
  - `reference` string, nullable: BKPF-XBLNR; maps to purchase_order_number
  - `assignment` string, nullable: BSEG-ZUONR
  - `debit_credit_indicator` 'S' | 'H', required: BSEG-SHKZG; S=debit/invoice, H=credit memo
  - `text` string, nullable: BSEG-SGTXT; max 50 chars; maps to Invoice.memo
  - `reason_code` string, nullable: BSEG-RSTGR; 3-char code
  - `clearing_document_number` string, nullable: BSEG-AUGBL
  - `clearing_date` string, date, nullable: BSEG-AUGCP; sets Invoice.paid_at
  - `status_open` boolean, nullable: Optional. True if the document came from BSID (open); False if from BSAD (cleared). When omitted, Stuut derives status from `clearing_date` — a row with a clearing date is treated as cleared (PAID), otherwise OPEN.
  - `billing_document` string, nullable: Original SD billing document number (VBRK-VBELN). Identifies the invoice on the SD side when the FI accounting doc differs.
  - `invoice_reference` string, nullable: BSEG-REBZG — accounting document number of the original invoice this clearing/payment line points at. Populated on payment & credit-memo lines that reference an invoice.
  - `payment_reference` string, nullable: Payment-side correlation token (e.g. BSEG-KIDNO, XREF1/2/3). Used to pair lockbox / EFT / ISO 20022 payments with the invoice they clear when assignment/reference are not specific enough.
  - `line_items` BoomiInvoiceLineItem[]
    - `line_number` integer, required: VBRP-POSNR
    - `description` string, nullable
    - `quantity` integer, nullable
    - `unit_amount` union: Unit amount in the invoice's currency (decimal, not cents)
      - number
      - string, decimal
    - `total_amount` union: Line total in the invoice's currency (decimal, not cents)
      - number
      - string, decimal

## Response `200`

Successful Response

- BoomiInboundResponse
  - `received_at` string, date-time, required
  - `results` BoomiInboundResult[], required
    - `remote_id` string, required
    - `success` boolean, required
    - `stuut_id` string, nullable, required
    - `error_code` string, nullable, required
    - `message` string, nullable, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/stuut/apis/stuut-api.md) - [All operations](https://skmtc.dev/stuut/apis/stuut-api/llms.txt) - [OpenAPI document](https://skmtc.dev/stuut/apis/stuut-api/revisions/ff0ad16a55ff?raw)