Surfaces

Interactive API Explorer: Explorer

The authoritative surface is the OpenAPI spec:

• /scm/openapi.yaml

Additional surfaces are available: MCP (/scm/mcp.html) and CLI (g3n scm ...; see cli/README.md).

Surface Types (explicit)

API Gateway

• Status: Available.
• Base: https://api.g3nretailstack.com/scm
• Notes: Primary tenant surface for sales cycle workflows.

Direct Lambda

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

CLI

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

MCP

• Status: Available.
• Canonical protocol: https://mcp.g3nretailstack.com/scm/PROTOCOL.md
• Mirror: https://doc.g3nretailstack.com/scm/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/scm/<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.

OMS/DOM expansion surfaces

• POST /scm/order/promise/quote (ATP/CTP promise quotes with confidence + routing plan preview)
• POST /scm/order/promise/reserve
• POST /scm/order/promise/allocate
• POST /scm/order/promise/commit
• POST /scm/order/promise/release
• POST /scm/routing/policy/get|list|set (routing policy CRUD by channel/logical)
• POST /scm/routing/plan/create|get|list (routing plans for split fulfillment)
• POST /scm/fulfillment/shipment/exception (custom exception codes + notes)
• POST /scm/fulfillment/shipment/exception/short-pick
• POST /scm/fulfillment/shipment/exception/damaged
• POST /scm/fulfillment/shipment/exception/carrier-failure
• POST /scm/fulfillment/shipment/exception/partial
• POST /scm/fulfillment/shipment/exception/resolve
• POST /scm/fulfillment/shipment/pickup/no_show

EDI adapter surfaces

• POST /scm/edi/record
• POST /scm/edi/status/set
• POST /scm/edi/get
• POST /scm/edi/list

Tax/compliance surfaces

• POST /scm/tax/policy/set|get|list
• POST /scm/tax/quote
• POST /scm/tax/finalize

Endpoint inventory (OpenAPI parity)

Request/response schema names reference OpenAPI component schemas.

Method	Path	Request schema	Response schema
POST	/backorder/approve	BackorderApproveRequest	BackorderEnvelope
POST	/backorder/cancel	BackorderCancelRequest	BackorderEnvelope
POST	/backorder/create	BackorderCreateRequest	BackorderEnvelope
POST	/backorder/expire	BackorderExpireRequest	BackorderEnvelope
POST	/backorder/fulfill	BackorderFulfillRequest	BackorderEnvelope
POST	/backorder/get	BackorderGetRequest	BackorderEnvelope
POST	/backorder/list	BackorderListRequest	BackorderListEnvelope
POST	/backorder/partial-fulfill	BackorderPartialFulfillRequest	BackorderEnvelope
POST	/backorder/promise	BackorderPromiseRequest	BackorderEnvelope
POST	/channel/policy/get	ChannelPolicyGetRequest	ChannelPolicyEnvelope
POST	/channel/policy/set	ChannelPolicySetRequest	ChannelPolicyEnvelope
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	/edi/get	EdiGetRequest	EdiEnvelope
POST	/edi/list	EdiListRequest	EdiListEnvelope
POST	/edi/record	EdiRecordRequest	EdiEnvelope
POST	/edi/status/set	EdiStatusSetRequest	EdiEnvelope
POST	/fulfillment/shipment/cancel	ShipmentCancelRequest	ShipmentEnvelope
POST	/fulfillment/shipment/create	ShipmentCreateRequest	ShipmentEnvelope
POST	/fulfillment/shipment/deliver	ShipmentDeliverRequest	ShipmentEnvelope
POST	/fulfillment/shipment/exception	ShipmentExceptionRequest	ShipmentEnvelope
POST	/fulfillment/shipment/exception/carrier-failure	ShipmentExceptionCarrierFailureRequest	ShipmentEnvelope
POST	/fulfillment/shipment/exception/damaged	ShipmentExceptionDamagedRequest	ShipmentEnvelope
POST	/fulfillment/shipment/exception/partial	ShipmentExceptionPartialRequest	ShipmentEnvelope
POST	/fulfillment/shipment/exception/resolve	ShipmentExceptionResolveRequest	ShipmentEnvelope
POST	/fulfillment/shipment/exception/short-pick	ShipmentExceptionShortPickRequest	ShipmentEnvelope
POST	/fulfillment/shipment/get	ShipmentGetRequest	ShipmentEnvelope
POST	/fulfillment/shipment/list	ShipmentListRequest	ShipmentListEnvelope
POST	/fulfillment/shipment/pack	ShipmentPackRequest	ShipmentEnvelope
POST	/fulfillment/shipment/pick	ShipmentPickRequest	ShipmentEnvelope
POST	/fulfillment/shipment/pickup/complete	ShipmentPickupCompleteRequest	ShipmentEnvelope
POST	/fulfillment/shipment/pickup/no_show	ShipmentPickupNoShowRequest	ShipmentEnvelope
POST	/fulfillment/shipment/pickup/ready	ShipmentPickupReadyRequest	ShipmentEnvelope
POST	/fulfillment/shipment/ship	ShipmentShipRequest	ShipmentEnvelope
POST	/fulfillment/shipment/substitution/apply	ShipmentSubstitutionApplyRequest	ShipmentEnvelope
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	/order/cancel	OrderCancelRequest	OrderEnvelope
POST	/order/close	OrderCloseRequest	OrderEnvelope
POST	/order/create	OrderCreateRequest	OrderEnvelope
POST	/order/fulfill	OrderFulfillRequest	OrderEnvelope
POST	/order/get	OrderGetRequest	OrderEnvelope
POST	/order/line/cancel	OrderLineCancelRequest	OrderEnvelope
POST	/order/list	OrderListRequest	OrderListEnvelope
POST	/order/place	OrderPlaceRequest	OrderEnvelope
POST	/order/promise/allocate	OrderPromiseAllocateRequest	OrderEnvelope
POST	/order/promise/commit	OrderPromiseCommitRequest	OrderEnvelope
POST	/order/promise/quote	OrderPromiseQuoteRequest	PromiseQuoteEnvelope
POST	/order/promise/release	OrderPromiseReleaseRequest	OrderEnvelope
POST	/order/promise/reserve	OrderPromiseReserveRequest	OrderEnvelope
POST	/order/search	OrderSearchRequest	OrderListEnvelope
POST	/quote/accept	QuoteAcceptRequest	QuoteEnvelope
POST	/quote/approve	QuoteApproveRequest	QuoteEnvelope
POST	/quote/convert	QuoteConvertRequest	OrderEnvelope
POST	/quote/create	QuoteCreateRequest	QuoteEnvelope
POST	/quote/expire	QuoteExpireRequest	QuoteEnvelope
POST	/quote/get	QuoteGetRequest	QuoteEnvelope
POST	/quote/list	QuoteListRequest	QuoteListEnvelope
POST	/quote/reject	QuoteRejectRequest	QuoteEnvelope
POST	/quote/send	QuoteSendRequest	QuoteEnvelope
POST	/refund/issue	RefundRequest	RefundEnvelope
POST	/return/authorize	ReturnAuthorizeRequest	ReturnEnvelope
POST	/return/get	ReturnGetRequest	ReturnEnvelope
POST	/return/inspect	ReturnInspectRequest	ReturnEnvelope
POST	/return/list	ReturnListRequest	ReturnListEnvelope
POST	/return/receive	ReturnReceiveRequest	ReturnEnvelope
POST	/return/request	ReturnRequest	ReturnEnvelope
POST	/return/resolve	ReturnResolveRequest	ReturnEnvelope
POST	/routing/plan/create	RoutingPlanCreateRequest	RoutingPlanEnvelope
POST	/routing/plan/get	RoutingPlanGetRequest	RoutingPlanEnvelope
POST	/routing/plan/list	RoutingPlanListRequest	RoutingPlanListEnvelope
POST	/routing/policy/get	RoutingPolicyGetRequest	RoutingPolicyEnvelope
POST	/routing/policy/list	RoutingPolicyListRequest	RoutingPolicyListEnvelope
POST	/routing/policy/set	RoutingPolicySetRequest	RoutingPolicyEnvelope
POST	/special-order/approve	SpecialOrderApproveRequest	SpecialOrderEnvelope
POST	/special-order/cancel	SpecialOrderCancelRequest	SpecialOrderEnvelope
POST	/special-order/create	SpecialOrderCreateRequest	SpecialOrderEnvelope
POST	/special-order/get	SpecialOrderGetRequest	SpecialOrderEnvelope
POST	/special-order/list	SpecialOrderListRequest	SpecialOrderListEnvelope
POST	/special-order/submit	SpecialOrderSubmitRequest	SpecialOrderEnvelope
POST	/tax/finalize	TaxFinalizeRequest	TaxRecordEnvelope
POST	/tax/policy/get	TaxPolicyGetRequest	TaxPolicyEnvelope
POST	/tax/policy/list	TaxPolicyListRequest	TaxPolicyListEnvelope
POST	/tax/policy/set	TaxPolicySetRequest	TaxPolicyEnvelope
POST	/tax/quote	TaxQuoteRequest	TaxQuoteEnvelope
POST	/tender/capture	TenderCaptureRequest	TenderEnvelope
POST	/tender/get	TenderGetRequest	TenderEnvelope
POST	/tender/list	TenderListRequest	TenderListEnvelope
POST	/tender/settle	TenderSettleRequest	TenderEnvelope
POST	/tender/void	TenderVoidRequest	TenderEnvelope

Entity lifecycle (state machines)

• Quote: draft → approved → sent → accepted / expired / rejected, accepted → converted
• Backorder: draft → approved → promised → partially_fulfilled → fulfilled / cancelled / expired
• Return: requested → authorized → received → inspected → resolved
• Order: draft → placed → fulfilled → closed / cancelled

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": "scm", "timestamp_utc": "2026-01-21T00:00:00Z" }
}

Error envelope (shape-only):

{
  "success": false,
  "error": {
    "error_code": "scm.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": "scm", "timestamp_utc": "2026-01-21T00:00:00Z", "request_id": "req-123" }
}

Role requirements (by endpoint family)

• Read/list/search: scm_view (or owner).
• Order placement & promise: scm_order (or owner).
• Fulfillment & shipments: scm_fulfillment (or owner).
• Returns/refunds: scm_returns / scm_credit (or owner).
• Approvals: scm_discount_approve, scm_special_order_approve, scm_backorder_approve as applicable.

Idempotency & retries

• Use expected_revision for state changes (order status, shipment status).
• 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.
• Promise/allocate/commit flows must be sequenced; use release on cancel.
• Comment/inbox lists default to status=current / status=inbox; use status=all to include archived/doomed.

Examples (core families)

Order create

{ "logical_guid": "LOGICAL_GUID", "channel_code": "WEB", "items": [{ "variant_id": "VARIANT_ID", "qty": 1 }], "reason": "checkout" }

Response (shape):

{ "success": true, "data": { "order_id": "ORDER_ID" }, "build": { "...": "..." }, "stats": { "...": "..." } }

Shipment record

{ "order_id": "ORDER_ID", "shipment": { "carrier": "UPS", "tracking": "1Z..." }, "reason": "ship" }

Response (shape):

{ "success": true, "data": { "shipment_id": "SHIP_ID" }, "build": { "...": "..." }, "stats": { "...": "..." } }