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

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

`POST /v2/integrations/providers/sap-btp/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/sap-btp/invoices`
- Auth: HTTP bearer

Maximum 100 records per request. ``debit_credit_code`` S = Invoice,
H = CreditMemo. Invoice status is derived from ``clearing_date``.

## Request body

- union[]
  - union
    - InvoicePayload: Standard receivable; S means invoice and H means credit memo.
      - `custom_fields` object, nullable: Source-specific values without a standard field.
      - `invoice_number` string, required
      - `line_item` string, required
      - `fiscal_year` string, required
      - `company_code` string, required
      - `customer_id` string, required
      - `document_type` string, required
      - `debit_credit_code` 'S' | 'H', required
      - `total_amount` union, required
        - number
        - string, decimal
      - `currency` string, required
      - `issued_date` string, date, required
      - `due_date` string, date, required
      - `clearing_date` string, date, nullable
      - `number` string, nullable
      - `purchase_order_number` string, nullable
      - `memo` string, nullable
      - `contract_number` string, nullable
      - `order_number` string, nullable
      - `invoice_reference` string, nullable
      - `in_dispute` boolean, nullable
      - `disputed_amount` union
        - number
        - string, decimal
      - `promised_to_pay_date` string, date, nullable
    - SapBtpInvoicePayload: Invoice/credit-memo record in the existing Honeywell iFlow format. Routing: DG and negative RV = credit memo; other records = invoice. ``clearing_date`` null = OPEN, present = PAID. For receivables, ``currency`` is document currency and custom field ``open_invoice_amount`` supplies each source item's unsigned remaining amount. The row's accounting sign is preserved when grouping source items. ``original_invoice_amount`` supplies the original amount per SAP line; original-document lines are summed to obtain the invoice face value. The grouped writer stores net remaining in amount_due with amount_paid=0; recorded payments and credits are not subtracted from that balance again. When a configured local currency differs, receivable rows require an open document amount. Cash rows and credit-memo mapping follow separate paths.
      - `document_number` string, required: BELNR; 10-digit SAP doc number
      - `line_item` string, required: BUZEI; line item number
      - `customer` string, required: KUNNR; must match a pushed customer_number
      - `document_type` string, required: BLART; DG and negative RV = credit memo; other records = invoice
      - `amount_in_lc` union, required: DMBTR; amount in local currency, major unit
        - number
        - string, decimal
      - `currency` string, required: WAERS; ISO 4217
      - `posting_date` string, date, required: BUDAT; SAP posting date
      - `invoice_due_date` string, date, required: NETDT; net due date
      - `clearing_date` string, date, nullable: AUGDT; null = open, present = paid
      - `purchase_order` string, nullable: BSTKD; customer PO
      - `text` string, nullable: SGTXT; item text
      - `service_contract` string, nullable: XREF2; service contract
      - `billing_document_number` string, nullable: VBELN; billing document
      - `invoice_reference` string, nullable: REBZG; for credit memos, the invoice this CM is against
      - `promise_to_pay_date` string, date, nullable: FIN_P2P_DATE; promise-to-pay date
      - `disputed_invoice_amount` union: UDM_DISPUTED_AMT; amount under dispute
        - number
        - string, decimal
      - `custom_fields` object, nullable: SAP-specific fields stored as-is. Expected keys: company_code, fiscal_year, payment_terms, amount_in_usd, original_invoice_no, original_invoice_amount, original_invoice_amount_usd, open_invoice_amount, assignment, promise_pay_amount, dispute_status, dispute_reason, dispute_root_cause, dispute_case_id

## Response `200`

Successful Response

- SapBtpInboundResponse: Common envelope for processing results and request-level errors. Request-level errors retain their HTTP status and return one failed result with an empty remote_id. No unauthenticated body is parsed to identify records. Validation failures retain their per-record results. Server errors expose a generic message; their exception reporting remains with the API.
  - `received_at` string, date-time, required
  - `results` SapBtpRecordResult[], required
    - `remote_id` string, required
    - `success` boolean, required
    - `stuut_id` string, nullable, required
    - `error_code` string, nullable, required
    - `message` string, nullable, required

## Other responses

- `401`: Missing or invalid bearer token.
- `403`: Access denied.
- `413`: Batch exceeds the record limit.
- `422`: Batch rejected; no records processed.
- `429`: Rate limit exceeded.
- `500`: Internal server error.
- `default`: Request failed.

---

[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)