Playbooks

Playbooks are standard operating procedures (SOPs) for SCM. Use calls.md for payload shape and required fields.

Surface availability (explicit)

• API Gateway: Available.
• Direct Lambda: Not offered.
• CLI: Available (g3n scm ..., API Gateway).
• MCP: Available.

Playbook: Order → promise → fulfill → ship

Goal: Create an order, reserve inventory, and move it through fulfillment.

Why this sequence:

• Promise/reserve controls inventory availability for the order.
• Shipments must be created and transitioned in order.

Preconditions

• Valid orgcode, channel, and logical facility context (OFM).
• Items exist in PVM and stock is available (ICS).

SOP (happy path)

1. Quote promise (POST /order/promise/quote).
   • Reason: checks availability before committing.
2. Create order (POST /order/create) and place (POST /order/place).
   • Reason: records the sale and transitions to an actionable state.
3. Reserve inventory (POST /order/promise/reserve) and commit (POST /order/promise/commit).
   • Reason: holds and then commits stock for fulfillment.
4. Create shipment (POST /fulfillment/shipment/create).
   • Reason: defines fulfillment units and routing.
5. Pick + pack (POST /fulfillment/shipment/pick, /fulfillment/shipment/pack).
   • Reason: captures warehouse handling steps.
6. Ship (POST /fulfillment/shipment/ship) and deliver (POST /fulfillment/shipment/deliver).
   • Reason: completes outbound fulfillment lifecycle.
7. Settle tender (POST /tender/capture, /tender/settle) if applicable.
   • Reason: records liability and settlement.

Outputs

• Placed order with fulfilled shipments.
• Inventory commitments and tender records captured.

Failure modes / remediation

• insufficient-stock: re-run promise quote or adjust allocations.
• Shipment exceptions: use /fulfillment/shipment/exception/* then resolve.

Cross-service relationships

• ICS: stock movements.
• PPM: price resolution inputs for order totals.

Playbook: Returns + refunds

Goal: Process a return and issue refunds with proper tracking.

Why this sequence:

• Returns change inventory state and may trigger tender adjustments.

Preconditions

• Original order/shipments exist.

SOP (happy path)

1. Request return (POST /return/request).
   • Reason: captures return intent and items.
2. Receive return (POST /return/receive).
   • Reason: confirms physical receipt of items.
3. Issue refund (POST /refund/issue).
   • Reason: returns value to the customer.
4. Adjust tender liability (POST /tender/void or /tender/settle) as needed.
   • Reason: keeps tender ledger accurate.
5. List returns (POST /return/list) and get (POST /return/get) for audit.
   • Reason: verify status and history.

Outputs

• Return record and associated refund.

Failure modes / remediation

• invalid-state: ensure return is receivable before receiving.
• Tender conflicts: re-check tender status before void/settle.

Cross-service relationships

• ICS: returned stock re-entry.