s4hana-create-goods-receipt

name

s4hana-create-goods-receipt

description

Create Goods Receipts (Material Documents) in SAP S/4HANA Cloud Public or on-prem private edition via OData V2 A_MaterialDocumentHeader deep-insert at API_MATERIAL_DOCUMENT_SRV. Use whenever the user wants to create, post, add, generate, seed, receive, or confirm receipt of goods on S/4HANA — phrases like "post a goods receipt", "receive goods for PO X", "create GR for these POs", "seed GR demo data", "post GRs", "complete the 3-way match", "post material document". Handles full header + item deep-insert, CSRF flow, partial vs full receipt, idempotent bulk batches with per-record logging, and the GoodsMovementRefDocType=B requirement for PO-based receipts. Do NOT use for goods issues (movement types 201/261/etc.), stock transfers (movement types 311/411/etc.), or inventory counts (use Physical Inventory API).

s4hana-create-goods-receipt

Create Goods Receipts (Material Documents) on SAP S/4HANA Cloud Public. Verified production-ready against my438741.s4hana.cloud.sap 2026-05-12 — Material Documents 5000000001 + 5000000002 posted via API.

When to trigger

Verbs: create / post / add / generate / seed / receive / confirm Objects: GR(s), Goods Receipt(s), Material Document(s), receipt of goods Counts: 1 to ~100 records.

Hard rules (never violate)

1. Always do a 1-record live POST as a probe before bulk (≥3 records).
2. Never invent material/PO IDs — Material must match the referenced PO line exactly (M7/360 if mismatched).
3. If a required field has no sensible default and the user didn't specify → ask once, then auto-pick.
4. Scripts go in <cwd>/.s4hana-tmp/create-grs-<YYYYMMDD-HHMM>/. Never commit, never modify .env.
5. POSTs are sequential with 200ms delay; halt on 3 consecutive failures.
6. Do NOT include PurchaseOrder/PurchaseOrderItem fields WITHOUT also including GoodsMovementRefDocType="B" — the API rejects the fields as "not supported for type 101" without that hint.

Endpoint

• Service path: /sap/opu/odata/sap/API_MATERIAL_DOCUMENT_SRV
• Entity sets: A_MaterialDocumentHeader, A_MaterialDocumentItem
• Method: POST (deep-insert with to_MaterialDocumentItem)
• Communication scenario: SAP_COM_0108 — "Material Document Integration"

Phase 0 — Setup check (always do this first)

Before any other action, run the credential-presence check documented in shared/setup-check.md. In short:

1. Is there a .env in the user's working directory, OR are SAP_HOST / SAP_AUTH_MODE already exported in shell? If yes, skip and proceed to Phase 1.
2. If neither, find the plugin's .env.example (typically under ~/.claude/plugins/), offer to copy it to the user's ./.env, append .env to .gitignore if present, and wait for the user to fill in values before running the main task.

Phases

Phase 1 — Parse & gather input

Per GR, required:

Field	Notes
PurchaseOrder + PurchaseOrderItem	The PO line being received against
Material	Must EXACTLY match the PO line's material (M7/360 otherwise)
Plant	Match PO line
StorageLocation	Default 101A for plant 1010 on my438741. Varies by tenant.
QuantityInEntryUnit + EntryUnit	Partial receipts allowed (typical: 25–100% of order qty)
PostingDate	Must be in open MM posting period — same gate as SES (typically 2025/07 or 2025/08 on this tenant)
GoodsMovementType	"101" = Receipt for PO to warehouse (most common)
GoodsMovementRefDocType	"B" for PO reference (without this, PURCHASEORDER fields are rejected)

If user said "auto" or "random", pull eligible PO lines:

GET /sap/opu/odata/sap/API_PURCHASEORDER_PROCESS_SRV/A_PurchaseOrderItem?$filter=ProductType eq '1' and PurchaseOrderItemCategory eq '0' and IsCompletelyDelivered eq false&$select=PurchaseOrder,PurchaseOrderItem,Material,Plant,OrderQuantity,PurchaseOrderQuantityUnit

Skip PO lines whose Material is M7/175: Maintain serial numbers (serialized materials need extra fields).

Phase 2 — Tenant defaults

Cache via tenant memory. For my438741:

Setting	Value
Plant	1010
StorageLocation default	101A
GoodsMovementCode (header)	"01"
GoodsMovementType (item)	"101"
GoodsMovementRefDocType (item)	"B"
Open MM posting period	2025/07, 2025/08 (verify with M7/053 if uncertain)

Phase 3 — Build payload

Verified working envelope:

{
  "DocumentDate": "/Date(<ms>)/",
  "PostingDate": "/Date(<ms>)/",
  "MaterialDocumentHeaderText": "API GR batch ABC",
  "GoodsMovementCode": "01",
  "to_MaterialDocumentItem": [
    {
      "Material": "FG041",
      "Plant": "1010",
      "StorageLocation": "101A",
      "GoodsMovementType": "101",
      "GoodsMovementRefDocType": "B",
      "PurchaseOrder": "4500000000",
      "PurchaseOrderItem": "10",
      "QuantityInEntryUnit": "250",
      "EntryUnit": "PC"
    
  

Critical field — GoodsMovementRefDocType="B": SAP V2 OData treats type 101 with PurchaseOrder fields as ambiguous unless you also pass GoodsMovementRefDocType="B" (B = Purchase Order). Without it: MM_IM_ODATA_API_MDOC/011: Property PURCHASEORDER is not supported for GoodsMovementType 101. Easy fix, but unintuitive — easy to miss.

Phase 4 — CSRF + POST

Standard OData V2 CSRF flow — see ../s4hana-create-po/references/csrf-flow.md. MaterialDocument ID is auto-assigned in 500000000x range, paired with MaterialDocumentYear.

Phase 5 — Verify

GET /A_MaterialDocumentHeader(MaterialDocument='<id>',MaterialDocumentYear='<yr>')?$expand=to_MaterialDocumentItem

After GR posting, the referenced PO line's IsCompletelyDelivered, GoodsReceiptQuantity, and related stock fields update automatically.

Known error catalog

Code	Cause	Fix
MM_IM_ODATA_API_MDOC/011	"Property PURCHASEORDER not supported for GoodsMovementType 101"	Add GoodsMovementRefDocType="B" on the item
MM_IM_ODATA_API_MDOC/014	"Material Document processing failed"	Generic — read other error rows in the response for specifics
M7/360	"Material document data and PO data do not match (Material)"	Material on GR item must match PO line material exactly
M7/001	"Check table EKPO: entry ... does not exist"	The PurchaseOrderItem doesn't exist on the PO. Verify with a GET first
M7/175	"Maintain serial numbers for total quantity"	Material requires serial-number tracking — needs to_SerialNumber deep-insert (out of scope for typical demo)
M7/053	"Posting only possible in periods YYYY/MM"	PostingDate outside open MM period — backdate or open current period
ME/006	"User X already processing Purchasing doc item Y"	Lock — another session is editing the PO. Wait 5–30s and retry, or pick a different PO
403 You do not have start authorization for R3TR IWSV API_MATERIAL_DOCUMENT_SRV	Comm arrangement SAP_COM_0108 not added	Add the arrangement in Fiori → Communication Arrangements → New → SAP_COM_0108

Output structure

<cwd>/.s4hana-tmp/create-grs-<YYYYMMDD-HHMM>/
├── eligible-po-lines.json
├── create-log.jsonl
├── results.json
└── verify-sample.json

Reference files

• references/envelope-template.md — full schema with optional fields
• references/movement-types.md — common movement-type codes and their semantics
• scripts/bulk-gr-poster.mjs — reference implementation