Surfaces

Interactive API Explorer: Explorer

The authoritative surface is the OpenAPI spec:

• /ics/openapi.yaml

Additional surfaces include MCP and CLI (see below). Direct Lambda is not offered for ICS.

Surface Types (explicit)

API Gateway

• Status: Available.
• Base: https://api.g3nretailstack.com/ics
• Notes: Primary tenant surface for inventory workflows.

Direct Lambda

• Status: Not offered.
• Notes: No direct Lambda surface is documented for ICS.

CLI

• Status: Available.
• Command: g3n ics ... (API Gateway).
• Notes: See cli/README.md.

MCP

• Status: Available.
• Canonical protocol: https://mcp.g3nretailstack.com/ics/PROTOCOL.md
• Mirror: https://doc.g3nretailstack.com/ics/PROTOCOL.md

Auth + tenancy

• Required headers: x-orgcode and x-session-guid (user session) or x-api-key (org-bound service account).
• Header auth is canonical; body auth is accepted where documented. See /common/headers-identity.html.
• Optional cost attribution: x-cccode (or request field cccode) where supported; see OpenAPI.
• Non-associated callers receive 404 not-found (anti-enumeration).
• Facility context: x-logical-guid (required for operational actions; see OpenAPI per-path). x-channel-code (required where documented; see OpenAPI per-path).

Identifier policy

• Direct get/update/status calls require GUID/ID fields (*_id or legacy *_guid where that is the canonical field name). Code-based lookups are resolve/search only.
• Responses never include both *_id and *_guid for the same record (no dual-field output).
• Exceptions (email-based UAS, PVM resolve, MRS container+record_id) are listed in /common/ids-codes.html.

Request builder (API Gateway)

Headers (canonical)

-H "x-orgcode: $ORGCODE"
-H "x-session-guid: $SESSION_GUID" # or: -H "x-api-key: $API_KEY"
-H "content-type: application/json"

Template

curl -sS -X POST "https://api.g3nretailstack.com/ics/<endpoint>" \
  -H "content-type: application/json" \
  -H "x-orgcode: $ORGCODE" \
  -H "x-session-guid: $SESSION_GUID" \
  -d '{"...": "..."}'

Notes

• Replace <endpoint> with a route from the OpenAPI inventory.
• Header auth is canonical; body session_guid / api_key is accepted where documented.

Key endpoints (high-level)

• POST /ics/receive/record + /ics/receive/get + /ics/receive/list — record receipts and list/get by logical facility.
• POST /ics/qc/complete — complete QC and move quarantine → available/damaged with line-level outcomes.
• POST /ics/putaway/record + /ics/pick/record + /ics/pack/record + /ics/ship/record — movement workflows.
• POST /ics/replenishment/record + /ics/replenishment/suggest — bin replenishment movements + suggestions.
• POST /ics/stock/get + /ics/stock/list — SKU-only lookups without logical_guid return a list across authorized logical facilities (include logical_guid).
• POST /ics/stock/policy/get + /ics/stock/policy/set — per logical facility + variant negative stock protection policy.
• POST /ics/stock/transition — reclassify quantities between available, quarantine, and damaged buckets.
• POST /ics/count/plan/set|get|list|status — cycle count program configuration.
• POST /ics/count/create|submit|approve|reject — cycle count execution and approvals.
• POST /ics/comment|comment/get|comment/list|comment/revise|comment/status|comment/report — record-level comments.
• POST /ics/inbox/create|get|list|status|state — team inbox notifications.
• POST /ics/search/comments + POST /ics/search/inbox — org-wide search across comments/inbox (ICS/SCM/PCM/CRM/PPM/Influencer/Accounting).

Endpoint inventory (OpenAPI parity)

Request/response schema names reference OpenAPI component schemas.

Method	Path	Request schema	Response schema
POST	/adjustment/create	AdjustmentCreateRequest	AdjustmentEnvelope
POST	/allocation/create	AllocationCreateRequest	AllocationEnvelope
POST	/allocation/expire	AllocationExpireRequest	AllocationEnvelope
POST	/allocation/release	AllocationReleaseRequest	AllocationEnvelope
POST	/allocation/suggest	AllocationSuggestRequest	AllocationSuggestEnvelope
POST	/bin/create	BinCreateRequest	BinEnvelope
POST	/bin/get	BinGetRequest	BinEnvelope
POST	/bin/list	BinListRequest	BinListEnvelope
POST	/bin/status/set	BinStatusSetRequest	BinEnvelope
POST	/comment	CommentAddRequest	CommentEnvelope
POST	/comment/get	CommentGetRequest	CommentEnvelope
POST	/comment/list	CommentListRequest	CommentListEnvelope
POST	/comment/report	CommentReportRequest	CommentReportEnvelope
POST	/comment/revise	CommentReviseRequest	CommentEnvelope
POST	/comment/status	CommentStatusRequest	CommentEnvelope
POST	/commit/create	CommitCreateRequest	CommitEnvelope
POST	/commit/release	CommitReleaseRequest	CommitEnvelope
POST	/consignment/consume	ConsignmentConsumeRequest	ConsignmentEnvelope
POST	/consignment/receive	ConsignmentReceiveRequest	ConsignmentEnvelope
POST	/consignment/settle	ConsignmentSettlementRequest	ConsignmentEnvelope
POST	/count/approve	CountApproveRequest	CountEnvelope
POST	/count/create	CountCreateRequest	CountEnvelope
POST	/count/plan/get	CountPlanGetRequest	CountPlanEnvelope
POST	/count/plan/list	CountPlanListRequest	CountPlanListEnvelope
POST	/count/plan/set	CountPlanSetRequest	CountPlanEnvelope
POST	/count/plan/status/set	CountPlanStatusSetRequest	CountPlanEnvelope
POST	/count/reject	CountRejectRequest	CountEnvelope
POST	/count/submit	CountSubmitRequest	CountEnvelope
POST	/inbox/create	InboxCreateRequest	InboxEnvelope
POST	/inbox/get	InboxGetRequest	InboxEnvelope
POST	/inbox/list	InboxListRequest	InboxListEnvelope
POST	/inbox/state	InboxStateRequest	InboxEnvelope
POST	/inbox/status	InboxStatusRequest	InboxEnvelope
POST	/pack/record	PackRecordRequest	StockCardEntryEnvelope
POST	/pick/record	PickRecordRequest	StockCardEntryEnvelope
POST	/putaway/record	PutawayRecordRequest	StockCardEntryEnvelope
POST	/qc/complete	QcCompleteRequest	ReceiveEnvelope
POST	/receive/get	ReceiveGetRequest	ReceiveEnvelope
POST	/receive/list	ReceiveListRequest	ReceiveListEnvelope
POST	/receive/record	ReceiveRecordRequest	ReceiveEnvelope
POST	/replenishment/record	ReplenishmentRecordRequest	StockCardEntryEnvelope
POST	/replenishment/rule/get	ReplenishmentRuleGetRequest	ReplenishmentRuleEnvelope
POST	/replenishment/rule/list	ReplenishmentRuleListRequest	ReplenishmentRuleListEnvelope
POST	/replenishment/rule/set	ReplenishmentRuleSetRequest	ReplenishmentRuleEnvelope
POST	/replenishment/rule/status/set	ReplenishmentRuleStatusSetRequest	ReplenishmentRuleEnvelope
POST	/replenishment/suggest	ReplenishmentSuggestRequest	ReplenishmentSuggestEnvelope
POST	/reservation/create	ReservationCreateRequest	ReservationEnvelope
POST	/reservation/expire	ReservationExpireRequest	ReservationEnvelope
POST	/reservation/release	ReservationReleaseRequest	ReservationEnvelope
POST	/stock/card/list	StockCardListRequest	StockCardEnvelope
POST	/stock/get	StockGetRequest	StockEnvelope
POST	/stock/list	StockListRequest	StockListEnvelope
POST	/stock/policy/get	StockPolicyGetRequest	StockPolicyEnvelope
POST	/stock/policy/set	StockPolicySetRequest	StockPolicyEnvelope
POST	/stock/transition	StockTransitionRequest	StockTransitionEnvelope
POST	/transfer/report	TransferReportRequest	TransferReportEnvelope
POST	/transfer/request/approve	TransferRequestApproveRequest	TransferEnvelope
POST	/transfer/request/create	TransferRequestCreateRequest	TransferEnvelope
POST	/transfer/request/get	TransferRequestGetRequest	TransferEnvelope
POST	/transfer/request/list	TransferRequestListRequest	TransferListEnvelope
POST	/transfer/request/submit	TransferRequestSubmitRequest	TransferEnvelope
POST	/transfer/shipment/get	TransferShipmentGetRequest	TransferShipmentEnvelope
POST	/transfer/shipment/list	TransferShipmentListRequest	TransferShipmentListEnvelope
POST	/transfer/shipment/receive	TransferReceiveRequest	TransferShipmentEnvelope
POST	/transfer/shipment/record	TransferShipmentRecordRequest	TransferShipmentEnvelope
POST	/transfer/suggest	TransferSuggestRequest	TransferSuggestEnvelope
POST	/search/comments	CommentSearchRequest	CommentSearchEnvelope
POST	/search/inbox	InboxSearchRequest	InboxSearchEnvelope
POST	/ship/record	ShipRecordRequest	StockCardEntryEnvelope
POST	/zone/create	ZoneCreateRequest	ZoneEnvelope
POST	/zone/get	ZoneGetRequest	ZoneEnvelope
POST	/zone/list	ZoneListRequest	ZoneListEnvelope
POST	/zone/status/set	ZoneStatusSetRequest	ZoneEnvelope

Error tags

Common tags (see /common/error-tags.html for definitions): validation-error, unauthorized, forbidden, not-found, expected-revision-required, conflict, invalid-state, throttled, internal-error.

Example envelopes

Success envelope (shape-only):

{
  "success": true,
  "data": { "example": "see schema for fields" },
  "build": { "build_major": "MONDAY", "build_minor": "0000000000", "build_id": "MONDAY-0000000000" },
  "stats": { "call": "example", "service": "ics", "timestamp_utc": "2026-01-21T00:00:00Z" }
}

Error envelope (shape-only):

{
  "success": false,
  "error": {
    "error_code": "ics.conflict_revision",
    "http_status": 409,
    "retryable": false,
    "request_id": "req-123",
    "trace_id": "trace-abc",
    "major": { "tag": "conflict", "message": { "en_US": "Expected revision does not match the current record." } },
    "details": { "expected_revision": "3", "current_revision": "4" },
    "conflict_snapshot": { "revision": 4 }
  },
  "build": { "...": "..." },
  "stats": { "call": "example", "service": "ics", "timestamp_utc": "2026-01-21T00:00:00Z", "request_id": "req-123" }
}

Role requirements (by endpoint family)

• Read/list/stock/inbox/comments: ics_view (or owner).
• Adjustments/movements/receiving: ics_operator or ics_adjust (or owner).
• Transfers: ics_transfer_approve for approvals; ics_operator for requests.
• Counts: ics_count for cycle count flows.

Idempotency & retries

• Use expected_revision for any update on revisioned records.
• Idempotent write endpoints accept idempotency_key (ASCII <=128 chars). When supplied, the service replays the original response for 24h; replays with a different payload return 409 idempotency-conflict.
• Calls without a documented idempotency key are not idempotent.

Common pitfalls

• Facility-scoped calls require logical_guid.
• Negative stock protection is enforced per logical + variant (see stock policy).
• Comment/inbox lists default to status=current / status=inbox; use status=all to include archived/doomed.

Examples (core families)

Stock get

{ "logical_guid": "LOGICAL_GUID", "variant_id": "VARIANT_ID" }

Response (shape):

{ "success": true, "data": { "stock": { "variant_id": "VARIANT_ID" } }, "build": { "...": "..." }, "stats": { "...": "..." } }

Adjustment create

{ "logical_guid": "LOGICAL_GUID", "variant_id": "VARIANT_ID", "qty_delta": 5, "reason": "cycle-count" }

Response (shape):

{ "success": true, "data": { "adjustment_id": "ADJ_ID" }, "build": { "...": "..." }, "stats": { "...": "..." } }