---
title: "Push a batch of customer master records from SAP BTP"
method: POST
path: "/v2/integrations/providers/sap-btp/customers"
tags: ["integrations"]
---

# Push a batch of customer master records from SAP BTP

`POST /v2/integrations/providers/sap-btp/customers`

## 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/customers`
- Auth: HTTP bearer

Maximum 100 records per request. Each record is upserted by
``id`` against Partner.remote_id within the tenant
resolved from the API key.

## Request body

- union[]
  - union
    - CustomerPayload: Standard customer; additional source fields must be nested in custom_fields.
      - `custom_fields` object, nullable: Source-specific values without a standard field.
      - `id` string, required
      - `name` string, required
      - `legal_name` string, nullable
      - `first_name` string, nullable
      - `last_name` string, nullable
      - `account_number` string, nullable
      - `parent_id` string
      - `is_active` boolean
      - `description` string, nullable
      - `email` string, nullable
      - `phone` string, nullable
      - `billing_address` BillingAddress
        - `line1` string, nullable
        - `line2` string, nullable
        - `city` string, nullable
        - `state` string, nullable
        - `postal_code` string, nullable
        - `country` string, nullable
      - `currency` string, nullable
      - `tax_number` string, nullable
      - `created_at` string, date, nullable
      - `modified_at` string, date, nullable
      - `assignee_id` string, nullable
    - SapBtpCustomerPayload: Customer record in the existing Honeywell iFlow format. Translated to the shared Partner input contract.
      - `customer_number` string, required: KNA1-KUNNR; the AR customer number
      - `name` string, required: KNA1-NAME1; primary company/person name
      - `is_active` boolean: NOT KNB1-SPERR; false = blocked
      - `country` string, nullable: KNA1-LAND1; ISO alpha-2 country code
      - `line1` string, nullable: Billing street address
      - `line2` string, nullable: Billing address continuation
      - `city` string, nullable
      - `state` string, nullable
      - `postal_code` string, nullable
      - `billing_address` BillingAddress
        - `line1` string, nullable
        - `line2` string, nullable
        - `city` string, nullable
        - `state` string, nullable
        - `postal_code` string, nullable
        - `country` string, nullable
      - `created_at` string, date, nullable: KNA1-ERDAT; ISO-8601
      - `custom_fields` object, nullable: Flexible key-value pairs; merged into existing. Expected SAP fields: company_code, accounting_clerk_code, accounting_clerk_name, accounting_clerk_email, payment_terms, head_office, language. Accounting clerk codes are two-character identifiers; whitespace is stripped and integer and single-digit string values are padded to two characters. Other strings are preserved for compatibility with existing customer pushes. Nonblank language also updates the customer's default language for calls and email when supported; blanks preserve the current setting. An unsupported language is stored unchanged and leaves the default unchanged; an advisory is recorded in integration history. The successful response is unchanged.

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