@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/01-TEMPLATES/versori/workflows/ingestion/graphql-mutations/template-ingestion-payload-json-order-update-graphql.md

@@ -1,1260 +1,1260 @@
----
-template_id: tpl-ingest-payload-json-to-order-update-graphql
-canonical_filename: template-ingestion-payload-json-order-update-graphql.md
-sdk_version: latest
-runtime: versori
-direction: ingestion
-source: payload-json
-destination: fluent-graphql
-entity: order
-format: json
-logging: versori
-status: stable
-features:
-  - direct-payload-processing
-  - json-parsing
-  - graphql-mutations
-  - order-query-before-update
-  - attribute-updates
----
-
-# Template: Ingestion - Payload JSON to Order Update GraphQL
-
-**SDK Version:** @fluentcommerce/fc-connect-sdk@latest
-**Last Updated:** 2025-01-24
-**Deployment Target:** Versori Platform
-
----
-
-## 📋 Implementation Prompt
-
-```
-I need a Versori webhook ingestion that:
-
-1) Receives JSON payload directly in webhook request body with orderRef and attributes
-2) Parses JSON to extract order reference and attributes
-3) Queries Fluent Commerce to get order ID by order reference
-4) Updates order attributes using updateOrder GraphQL mutation
-5) Returns success/error response
-6) Uses native Versori log from context
-
-Use the loaded docs to fill in SDK specifics and best practices.
-Keep the structure identical to the template; only adapt where needed.
-```
-
----
-
-## 📋 Template Overview
-
-This connector runs on the Versori platform. It receives JSON payloads directly via webhook with order reference and attributes, queries Fluent Commerce to get the order ID, and updates order attributes using GraphQL mutations. Most operational settings (Fluent account/connection) are configured via activation variables.
-
-### What This Template Does
-
-```
-┌────────────────────────────────────────────────────────────────┐
-│          INGESTION WORKFLOW              │
-└────────────────────────────────────────────────────────────────┘
-
-1. TRIGGER
-  └─ Webhook: HTTP POST endpoint receives JSON payload
-
-2. RECEIVE PAYLOAD
-  ├─ Extract JSON from request body (ctx.data or ctx.request)
-  ├─ Validate payload structure
-  └─ Log incoming request
-
-3. PARSE JSON
-  ├─ Parse JSON payload (if raw string)
-  ├─ Extract order reference
-  ├─ Extract attributes array
-  └─ Validate required fields
-
-4. QUERY ORDER
-  ├─ Query Fluent Commerce: order(ref: orderRef)
-  ├─ Get order ID and current state
-  ├─ Validate order exists
-  └─ Log order details
-
-5. BUILD UPDATE MUTATION
-  ├─ Construct UpdateOrderInput with ref
-  ├─ Map attributes to AttributeInput format
-  ├─ Preserve existing attributes (optional merge)
-  └─ Build GraphQL mutation variables
-
-6. EXECUTE MUTATION
-  ├─ Execute updateOrder GraphQL mutation
-  ├─ Handle success/error responses
-  └─ Log mutation result
-
-7. RETURN RESPONSE
-  ├─ Return success with order details
-  └─ Return error with details if failed
-```
-
-### Key Features
-
-- **Direct Payload Processing**: Receives JSON payload directly in webhook request body
-- **Order Query First**: Queries order by ref to get ID and validate existence
-- **GraphQL Mutation**: Uses updateOrder mutation to update attributes
-- **Attribute Mapping**: Converts payload attributes to Fluent AttributeInput format
-- **Error Handling**: Comprehensive error handling with detailed logging
-- **Native Versori Logging**: Uses Versori log from context
-
-### 📦 Package Information
-
-**SDK:** [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk) `latest`
-
-```bash
-npm install @fluentcommerce/fc-connect-sdk@latest
-```
-
----
-
-**Templates are designed for direct deployment; customize via activation variables.**
-
----
-
-## 📦 SDK Imports (Verified - Versori Optimized)
-
-```typescript
-// ✅ VERIFIED IMPORTS - These match actual SDK exports
-import { Buffer } from 'node:buffer'; // Required for Versori/Deno runtime
-import {
-  createClient, // Universal client factory
-  JSONParserService, // JSON parsing utility
-} from '@fluentcommerce/fc-connect-sdk';
-
-import type { FluentClient } from '@fluentcommerce/fc-connect-sdk';
-
-// Versori platform imports
-import { webhook, http } from '@versori/run';
-```
-
-**Note:** All imports are from actual SDK exports - this code compiles and runs as-is.
-
-**⚠️ CRITICAL - Buffer Import Required:**
-
-The `Buffer` import from `node:buffer` is **required** for Versori/Deno runtime compatibility:
-- Versori and Deno do NOT have `Buffer` as a global (unlike Node.js)
-- Without this import, code will crash with `ReferenceError: Buffer is not defined`
-- Always include this import in Versori templates, even if not directly used in the template code
-- Required for SDK internal operations and any Buffer usage in your code
-
-**✅ VERSORI PLATFORM - Use Native Logs:**
-
-- Use `log` from context: `const { log } = ctx;`
-- Native Versori logs are simpler and automatically integrated with platform monitoring
-
----
-
-## 🔐 Fluent Commerce Connection Setup
-
-**✅ BEST PRACTICE:** Store Fluent Commerce credentials in a Versori connection object:
-
-**Connection Configuration:**
-
-1. **Create Connection in Versori:**
-   - Name: `fluent_commerce`
-   - Type: HTTP Basic Auth or OAuth2
-   - Credentials: Fluent Commerce API credentials
-
-2. **Connection Variables:**
-   - `FLUENT_BASE_URL` - Fluent Commerce API base URL (e.g., `https://api.fluentcommerce.com`)
-   - `FLUENT_CLIENT_ID` - OAuth client ID (if using OAuth2)
-   - `FLUENT_CLIENT_SECRET` - OAuth client secret (if using OAuth2)
-   - `FLUENT_USERNAME` - Username (if using Basic Auth)
-   - `FLUENT_PASSWORD` - Password (if using Basic Auth)
-
-**Benefits:**
-- ✅ Credentials stored securely in Versori vault
-- ✅ Connection can be reused across workflows
-- ✅ No sensitive data in activation variables
-- ✅ Easier credential rotation
-
----
-
-## 📄 Expected JSON Payload Format
-
-The webhook accepts **flat key-value JSON payloads**. All fields except `orderRef` are automatically treated as order attributes.
-
-### ✅ PRIMARY FORMAT: Flat Key-Value Pairs (Recommended)
-
-**Simple format - just key-value pairs, no nested structure:**
-
-```json
-{
-  "orderRef": "ORD-12345",
-  "externalOrderId": "EXT-123456789",
-  "customerNotes": "Please leave package at front door",
-  "priority": "high",
-  "tags": "rush,gift"
-}
-```
-
-**Type Auto-Detection:**
-- Numbers → `INTEGER` or `FLOAT` (auto-detected)
-- Booleans → `BOOLEAN` (auto-detected)
-- Objects → `JSON` (stringified)
-- Strings → `STRING` (default)
-
-**cURL Example:**
-```bash
-curl -X POST https://{workspace}.versori.run/order-update \
-  -H "Content-Type: application/json" \
-  -H "X-API-Key: your-api-key" \
-  -d '{
-    "orderRef": "ORD-12345",
-    "externalOrderId": "EXT-123456789",
-    "customerNotes": "Please leave package at front door",
-    "priority": "high"
-  }'
-```
-
-### Complete Sample Payloads
-
-**Example 1: External System Reference Update**
-```json
-{
-  "orderRef": "ORD-0017326966182",
-  "externalOrderId": "EXT-123456789",
-  "sourceSystem": "ERP-SAP",
-  "integrationId": "INT-987654321"
-}
-```
-
-**Example 2: Customer Notes and Business Flags**
-```json
-{
-  "orderRef": "ORD-0017326966182",
-  "customerNotes": "Please leave package at front door",
-  "priority": "high",
-  "tags": "rush,gift",
-  "specialHandling": true
-}
-```
-
-**Note:** Metadata fields (`updateReason`, `updatedBy`, `timestamp`) are optional and excluded from attributes. All other fields are treated as order attributes.
-
----
-
-## GraphQL Mutations
-
-### Query Order by Reference
-
-```graphql
-query GetOrder($ref: String!) {
-  order(ref: $ref) {
-    id
-    ref
-    status
-    attributes {
-      name
-      type
-      value
-    }
-  }
-}
-```
-
-### Update Order Mutation
-
-```graphql
-mutation UpdateOrder($input: UpdateOrderInput!) {
-  updateOrder(input: $input) {
-    id
-    ref
-    status
-    attributes {
-      name
-      type
-      value
-    }
-  }
-}
-```
-
-**UpdateOrderInput Structure:**
-- `id` (ID!) - Order ID (required) - Must use Fluent internal ID, not reference
-- `attributes` (Array<AttributeInput>) - Attributes to update
-- `status` (String) - Optional status update
-- Other optional fields as per schema
-
-**Note:** UpdateOrderInput requires `id: ID!` (the Fluent internal ID), not `ref`. This is why the template queries the order first to get the ID.
-
-**AttributeInput Structure:**
-- `name` (String!) - Attribute name
-- `type` (String!) - Attribute type (STRING, INTEGER, FLOAT, BOOLEAN, JSON, DATE)
-- `value` (String!) - Attribute value (stringified for non-STRING types)
-
----
-
-## 🔧 Complete Production Code
-
-### Versori Workflows Structure
-
-**Key Concept**: Versori workflows are organized by **trigger type** at the first level, then by **specific workflow** with descriptive file names.
-
-**Trigger Types:**
-- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
-
-**Execution Steps (chained to triggers):**
-- **`http()`** → External API calls (chained from webhook)
-
-### Recommended Project Structure
-
-```
-order-update-webhook/
-├── index.ts                              # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   └── webhook/
-    │       └── order-update.ts           # Webhook: Order update handler
-    │
-    ├── services/
-    │   └── order-update.service.ts       # Shared orchestration logic
-    │
-    ├── utils/
-    │   └── response-status.utils.ts      # FC status code mapping utilities
-    │
-    └── types/
-        └── order-update.types.ts         # Type definitions
-```
-
-**Benefits:**
-- ✅ Clear structure (webhook handlers in `webhook/`)
-- ✅ Descriptive file names (easy to browse and understand)
-- ✅ Reusable code in `services/` (DRY principle)
-- ✅ Centralized type definitions
-- ✅ Utility functions for consistent error handling (FC status codes)
-
----
-
-## Workflow Files
-
-### 1. Webhook Workflow (`src/workflows/webhook/order-update.ts`)
-
-**Purpose**: Handle order update requests via webhook
-**Trigger**: HTTP POST
-**Endpoint**: `POST https://{workspace}.versori.run/order-update`
-**Use Cases**: Order attribute updates from external systems, status changes
-
-```typescript
-import { webhook, http } from '@versori/run';
-import { executeOrderUpdate } from '../../services/order-update.service';
-import { mapErrorToFCStatus } from '../../utils/response-status.utils';
-
-/**
- * Webhook: Order Update Handler
- *
- * Endpoint: POST https://{workspace}.versori.run/order-update
- * Request body: { "orderRef": "ORD-12345", "externalOrderId": "EXT-123", "customerNotes": "...", ... }
- *
- * Pattern: webhook().then(http()) - needs Fluent API access
- * Uses shared service: order-update.service.ts
- *
- * SECURITY: Authentication handled via connection parameter
- * No manual API key validation needed - Versori manages this via connection auth
- */
-export const orderUpdateWebhook = webhook('order-update', {
-  response: { mode: 'sync' }, // ✅ Sync mode: response sent when handler returns
-  connection: 'order-update-webhook', // Versori validates API key
-}).then(
-  http('process-order-update', { connection: 'fluent_commerce' }, async ctx => {
-    const { log, data } = ctx;
-
-    log.info('🚀 [WEBHOOK] Order update request received', {
-      timestamp: new Date().toISOString(),
-      hasPayload: !!data,
-    });
-
-    try {
-      // Reuse shared orchestration logic
-      const result = await executeOrderUpdate(ctx);
-
-      log.info('✅ [WEBHOOK] Order update completed successfully', {
-        orderRef: result.orderRef,
-        orderId: result.orderId,
-        attributesUpdated: result.attributesUpdated,
-      });
-
-      // Return response with FC200 status code
-      return {
-        success: true,
-        statusCode: result.statusCode,
-        orderRef: result.orderRef,
-        orderId: result.orderId,
-        attributesUpdated: result.attributesUpdated,
-        message: result.message || 'Order attributes updated successfully',
-      };
-    } catch (e: any) {
-      log.error('❌ [WEBHOOK] Order update failed', {
-        message: e?.message,
-        stack: e?.stack,
-      });
-
-      // Map error to FC status code
-      const fcStatus = mapErrorToFCStatus(e);
-
-      return {
-        success: false,
-        statusCode: fcStatus.statusCode,
-        retryable: fcStatus.retryable,
-        error: fcStatus.message,
-        details: e?.message || 'Unknown error occurred',
-      };
-    }
-  })
-);
-```
-
----
-
-### 2. Entry Point (`index.ts`)
-
-**Purpose**: Register all workflows with Versori platform
-
-```typescript
-/**
- * Entry Point - Registers all workflows with Versori platform
- *
- * Versori automatically discovers and registers exported workflows
- *
- * File Structure:
- * - src/workflows/webhook/   → HTTP-based triggers (webhooks)
- * - src/services/            → Shared service logic (reusable across workflows)
- */
-
-// Import webhook workflows
-import { orderUpdateWebhook } from './src/workflows/webhook/order-update';
-
-// Register all workflows with Versori platform
-export {
-  // Webhooks (HTTP-based triggers)
-  orderUpdateWebhook,
-};
-```
-
-**What Gets Exposed:**
-- ✅ `orderUpdateWebhook` → `https://{workspace}.versori.run/order-update`
-
----
-
-## 3. Type Definitions (`src/types/order-update.types.ts`)
-
-```typescript
-/**
- * Type Definitions for Order Update Ingestion
- *
- * Centralized type definitions for order update workflow
- */
-
-/**
- * Order update request payload
- *
- * PRIMARY FORMAT: Flat key-value pairs
- * - orderRef: Required order reference
- * - All other fields (except metadata fields) are treated as attributes
- *
- * Example:
- * {
- *   "orderRef": "ORD-12345",
- *   "externalOrderId": "EXT-123456789",
- *   "customerNotes": "Please leave package at front door",
- *   "priority": "high"
- * }
- */
-export interface OrderUpdatePayload {
-  orderRef: string;
-  // Flat attributes: all fields except orderRef are treated as attributes
-  [key: string]: string | number | boolean | unknown;
-}
-
-/**
- * Fluent AttributeInput format
- */
-export interface AttributeInput {
-  name: string;
-  type: 'STRING' | 'INTEGER' | 'FLOAT' | 'BOOLEAN' | 'JSON' | 'DATE';
-  value: string;
-}
-
-/**
- * Order query result
- */
-export interface OrderQueryResult {
-  id: string;
-  ref: string;
-  status?: string;
-  attributes?: Array<{
-    name: string;
-    type: string;
-    value: string;
-  }>;
-}
-
-/**
- * Order update result with FC status code
- */
-export interface OrderUpdateResult {
-  success: boolean;
-  statusCode: 'FC200' | 'FC400' | 'FC409' | 'FC504';
-  orderRef: string;
-  orderId: string;
-  attributesUpdated: number;
-  message?: string;
-  error?: string;
-  retryable?: boolean;
-}
-
-/**
- * Versori Context Interface
- * Represents the Versori runtime context passed to workflow functions
- */
-export interface VersoriContext {
-  log: {
-    info: (message: string, data?: Record<string, unknown>) => void;
-    warn: (message: string, data?: Record<string, unknown>) => void;
-    error: (message: string, data?: Record<string, unknown>) => void;
-    debug?: (message: string, data?: Record<string, unknown>) => void;
-  };
-  data?: unknown;
-  request?: Request;
-  activation: {
-    getVariable: (name: string) => string | undefined;
-    connections?: Record<string, unknown>;
-  };
-  connections?: Record<string, unknown>;
-}
-```
-
----
-
-## 4. Utility: Response Status Code Mapper (`src/utils/response-status.utils.ts`)
-
-```typescript
-/**
- * Response Status Code Utility
- *
- * Maps errors to Fluent Commerce (FC) status codes for consistent API responses
- */
-
-/**
- * FC Status Codes:
- * - FC200: OK (Successfully - No further action needed)
- * - FC400: Bad Request (Non-retryable)
- * - FC409: Duplicate Request, Entity already exists (Non-retryable)
- * - FC504: Timeout (Retryable)
- */
-
-export type FCStatusCode = 'FC200' | 'FC400' | 'FC409' | 'FC504';
-
-export interface FCStatusMapping {
-  statusCode: FCStatusCode;
-  retryable: boolean;
-  message: string;
-}
-
-/**
- * Map error to FC status code based on error message and type
- */
-export function mapErrorToFCStatus(error: unknown): FCStatusMapping {
-  const errorMessage =
-    error instanceof Error ? error.message : String(error);
-  const lowerMessage = errorMessage.toLowerCase();
-
-  // FC409: Duplicate/Already exists (Non-retryable)
-  if (
-    lowerMessage.includes('already exists') ||
-    lowerMessage.includes('duplicate') ||
-    lowerMessage.includes('unique constraint') ||
-    lowerMessage.includes('entity already exists')
-  ) {
-    return {
-      statusCode: 'FC409',
-      retryable: false,
-      message: 'Entity already exists. Duplicate request detected.',
-    };
-  }
-
-  // FC504: Timeout (Retryable)
-  if (
-    lowerMessage.includes('timeout') ||
-    lowerMessage.includes('timed out') ||
-    lowerMessage.includes('request timeout') ||
-    (error instanceof Error && error.name === 'TimeoutError')
-  ) {
-    return {
-      statusCode: 'FC504',
-      retryable: true,
-      message: 'Request timeout. Please retry.',
-    };
-  }
-
-  // FC400: Bad Request (Non-retryable)
-  // Validation errors, missing fields, invalid format
-  if (
-    lowerMessage.includes('required') ||
-    lowerMessage.includes('missing') ||
-    lowerMessage.includes('invalid') ||
-    lowerMessage.includes('bad request') ||
-    lowerMessage.includes('validation') ||
-    lowerMessage.includes('not found') ||
-    lowerMessage.includes('does not exist')
-  ) {
-    return {
-      statusCode: 'FC400',
-      retryable: false,
-      message: 'Bad request. Please verify payload and try again.',
-    };
-  }
-
-  // Default: FC400 for unknown errors (Non-retryable)
-  return {
-    statusCode: 'FC400',
-    retryable: false,
-    message: errorMessage,
-  };
-}
-
-/**
- * Create success response with FC200 status
- */
-export function createSuccessResponse<T extends Record<string, unknown>>(
-  data: T
-): T & { statusCode: 'FC200'; retryable: false } {
-  return {
-    ...data,
-    statusCode: 'FC200' as const,
-    retryable: false,
-  };
-}
-```
-
----
-
-## 5. Service: Order Update Processor (`src/services/order-update.service.ts`)
-
-```typescript
-/**
- * Order Update Service
- *
- * Processes order update requests: extracts order reference and attributes from JSON payload,
- * queries Fluent Commerce to get order ID, and updates order attributes via GraphQL mutation.
- */
-
-import {
-  createClient,
-  JSONParserService,
-} from '@fluentcommerce/fc-connect-sdk';
-import { Buffer } from 'node:buffer';
-import { mapErrorToFCStatus, createSuccessResponse } from '../utils/response-status.utils';
-import type { FluentClient } from '@fluentcommerce/fc-connect-sdk';
-import type {
-  OrderUpdatePayload,
-  OrderUpdateResult,
-  VersoriContext,
-  AttributeInput,
-  OrderQueryResult,
-} from '../types/order-update.types';
-
-/**
- * GraphQL query to get order by reference
- */
-const GET_ORDER_QUERY = `
-  query GetOrder($ref: String!) {
-    order(ref: $ref) {
-      id
-      ref
-      status
-      attributes {
-        name
-        type
-        value
-      }
-    }
-  }
-`;
-
-/**
- * GraphQL mutation to update order
- */
-const UPDATE_ORDER_MUTATION = `
-  mutation UpdateOrder($input: UpdateOrderInput!) {
-    updateOrder(input: $input) {
-      id
-      ref
-      status
-      attributes {
-        name
-        type
-        value
-      }
-    }
-  }
-`;
-
-/**
- * Extract attributes from flat payload format
- *
- * PRIMARY FORMAT: All fields except orderRef (and metadata fields) are attributes
- * - orderRef: Required, excluded from attributes
- * - Metadata fields: updateReason, updatedBy, timestamp (optional, excluded)
- * - All other fields: Treated as attributes with auto-detected types
- *
- * Example payload:
- * {
- *   "orderRef": "ORD-12345",
- *   "externalOrderId": "EXT-123456789",       // → attribute
- *   "customerNotes": "Front door",            // → attribute
- *   "priority": "high"                        // → attribute
- * }
- */
-function extractAttributesFromPayload(
-  payload: OrderUpdatePayload
-): AttributeInput[] {
-  const metadataFields = ['orderRef', 'updateReason', 'updatedBy', 'timestamp'];
-  const attributes: AttributeInput[] = [];
-
-  // Extract all fields except orderRef and metadata fields
-  for (const [name, value] of Object.entries(payload)) {
-    // Skip metadata fields
-    if (metadataFields.includes(name)) {
-      continue;
-    }
-
-    // Skip null/undefined values
-    if (value === null || value === undefined) {
-      continue;
-    }
-
-    // Auto-detect type from value
-    let type: AttributeInput['type'] = 'STRING';
-    let stringValue: string;
-
-    if (typeof value === 'number') {
-      type = Number.isInteger(value) ? 'INTEGER' : 'FLOAT';
-      stringValue = String(value);
-    } else if (typeof value === 'boolean') {
-      type = 'BOOLEAN';
-      stringValue = String(value);
-    } else if (typeof value === 'object') {
-      type = 'JSON';
-      stringValue = JSON.stringify(value);
-    } else {
-      // String or other types → STRING
-      stringValue = String(value);
-    }
-
-    attributes.push({
-      name,
-      type,
-      value: stringValue,
-    });
-  }
-
-  return attributes;
-}
-
-/**
- * Parse webhook payload from Versori context
- *
- * Handles both pre-parsed JSON (ctx.data) and raw request body (ctx.request)
- */
-async function parseWebhookPayload(
-  ctx: VersoriContext
-): Promise<OrderUpdatePayload | null> {
-  const { log, data, request } = ctx;
-
-  // Scenario 1: Pre-parsed JSON (Versori auto-parsed)
-  if (data && typeof data === 'object' && data !== null) {
-    log.info('📥 [PARSE] Using pre-parsed JSON payload', {
-      hasData: true,
-      dataKeys: Object.keys(data),
-    });
-    return data as OrderUpdatePayload;
-  }
-
-  // Scenario 2: Raw request body (need to parse)
-  if (request && typeof request.text === 'function') {
-    log.info('📥 [PARSE] Extracting raw request body');
-    try {
-      const rawBody = await request.text();
-      if (!rawBody || rawBody.trim() === '') {
-        log.error('❌ [PARSE] Request body is empty');
-        return null;
-      }
-
-      const parser = new JSONParserService(log);
-      const parsed = await parser.parse(rawBody);
-      
-      log.info('📥 [PARSE] Successfully parsed JSON payload', {
-        parsedKeys: Object.keys(parsed),
-      });
-      
-      return parsed as OrderUpdatePayload;
-    } catch (parseError: unknown) {
-      const errorMessage =
-        parseError instanceof Error ? parseError.message : String(parseError);
-      log.error('❌ [PARSE] Failed to parse JSON payload', {
-        error: errorMessage,
-      });
-      return null;
-    }
-  }
-
-  log.error('❌ [PARSE] No valid payload found in context');
-  return null;
-}
-
-/**
- * Query order by reference to get ID and current state
- */
-async function queryOrderByRef(
-  client: FluentClient,
-  orderRef: string,
-  log: VersoriContext['log']
-): Promise<OrderQueryResult> {
-  log.info('🔍 [QUERY] Querying order by reference', { orderRef });
-
-  const result = await client.graphql({
-    query: GET_ORDER_QUERY,
-    variables: { ref: orderRef },
-  });
-
-  if (result.errors && result.errors.length > 0) {
-    log.error('❌ [QUERY] GraphQL query returned errors', {
-      errors: result.errors,
-      orderRef,
-    });
-    throw new Error(`GraphQL query failed: ${result.errors[0].message}`);
-  }
-
-  const order = (result.data as any)?.order;
-
-  if (!order) {
-    log.error('❌ [QUERY] Order not found', { orderRef });
-    throw new Error(`Order not found: ${orderRef}`);
-  }
-
-  log.info('✅ [QUERY] Order found', {
-    orderId: order.id,
-    orderRef: order.ref,
-    status: order.status,
-    currentAttributeCount: order.attributes?.length || 0,
-  });
-
-  return order as OrderQueryResult;
-}
-
-/**
- * Execute order update workflow
- *
- * Main orchestration function:
- * 1. Parse webhook payload
- * 2. Extract order reference and attributes
- * 3. Create Fluent client
- * 4. Query order by reference to get ID
- * 5. Build update mutation variables
- * 6. Execute updateOrder mutation
- *
- * Note: Authentication handled via Versori connection (fluent_commerce).
- * Retailer ID is not required for GraphQL mutations - connection handles authentication.
- *
- * CRITICAL: UpdateOrderInput requires id: ID! (not ref).
- * The query step retrieves order.id which must be used in the mutation.
- */
-export async function executeOrderUpdate(
-  ctx: VersoriContext
-): Promise<OrderUpdateResult> {
-  const { log, activation } = ctx;
-
-  log.info('🚀 [SERVICE] Starting order update processing');
-
-  // STEP 1: Parse webhook payload
-  const payload = await parseWebhookPayload(ctx);
-  if (!payload) {
-    log.error('❌ [SERVICE] Failed to parse webhook payload', {
-      hasData: !!ctx.data,
-      hasRequest: !!ctx.request,
-    });
-    throw new Error('Failed to parse webhook payload. Ensure Content-Type: application/json is set in request headers.');
-  }
-
-  log.info('📥 [SERVICE] Payload parsed successfully', {
-    payloadKeys: Object.keys(payload),
-  });
-
-  // STEP 2: Extract order reference
-  if (!payload.orderRef || typeof payload.orderRef !== 'string') {
-    log.error('❌ [SERVICE] Order reference not found in payload', {
-      payloadKeys: Object.keys(payload),
-      expectedField: 'orderRef',
-    });
-    throw new Error('Order reference (orderRef) is required in payload');
-  }
-
-  const orderRef = payload.orderRef;
-  log.info('✅ [SERVICE] Order reference extracted', { orderRef });
-
-  // STEP 3: Extract attributes from flat payload format
-  // ✅ PRIMARY FORMAT: All fields except orderRef are treated as attributes
-  const attributes = extractAttributesFromPayload(payload);
-  if (attributes.length === 0) {
-    log.warn('⚠️ [SERVICE] No attributes provided in payload', {
-      orderRef,
-      payloadKeys: Object.keys(payload),
-    });
-    throw new Error('At least one attribute is required for order update. Provide fields like: { "orderRef": "ORD-123", "externalOrderId": "EXT-123", "customerNotes": "Leave at door" }');
-  }
-
-  log.info('✅ [SERVICE] Attributes extracted', {
-    orderRef,
-    attributeCount: attributes.length,
-    attributeNames: attributes.map(a => a.name),
-  });
-
-  // STEP 4: Create Fluent client
-  // ✅ Pass ctx directly - createClient auto-detects Versori context
-  // Authentication handled via Versori connection (fluent_commerce)
-  const client = await createClient(ctx);
-
-  log.info('✅ [SERVICE] Fluent client created');
-
-  // STEP 5: Query order by reference to get ID
-  // ✅ Query first to:
-  //    - Validate order exists (fail-fast if order not found)
-  //    - Get order ID for logging and tracking
-  //    - Get current order state (optional: can merge with existing attributes)
-  const order = await queryOrderByRef(client, orderRef, log);
-
-  // STEP 6: Build update mutation variables
-  // ✅ CRITICAL: UpdateOrderInput requires id: ID! (not ref)
-  //    Use the ID from queryOrderByRef result - this is why we query first!
-  const updateVariables = {
-    input: {
-      id: order.id, // ✅ REQUIRED: UpdateOrderInput.id is ID! (required field)
-      attributes: attributes,
-    },
-  };
-
-  log.info('📤 [SERVICE] Executing updateOrder mutation', {
-    orderRef,
-    orderId: order.id,
-    attributeCount: attributes.length,
-  });
-
-  // STEP 7: Execute updateOrder mutation
-  const mutationResult = await client.graphql({
-    query: UPDATE_ORDER_MUTATION,
-    variables: updateVariables,
-  });
-
-  if (mutationResult.errors && mutationResult.errors.length > 0) {
-    log.error('❌ [SERVICE] GraphQL mutation returned errors', {
-      errors: mutationResult.errors,
-      orderRef,
-      orderId: order.id,
-    });
-    throw new Error(`GraphQL mutation failed: ${mutationResult.errors[0].message}`);
-  }
-
-  const updatedOrder = (mutationResult.data as any)?.updateOrder;
-
-  if (!updatedOrder) {
-    log.error('❌ [SERVICE] No order data returned from mutation', { orderRef });
-    throw new Error('No order data returned from updateOrder mutation');
-  }
-
-  log.info('✅ [SERVICE] Order updated successfully', {
-    orderRef,
-    orderId: updatedOrder.id,
-    attributesUpdated: attributes.length,
-  });
-
-  // Return success response with FC200 status code
-  return createSuccessResponse({
-    success: true,
-    orderRef,
-    orderId: updatedOrder.id,
-    attributesUpdated: attributes.length,
-    message: 'Order attributes updated successfully',
-  });
-}
-```
-
----
-
-## 5. Configuration
-
-### Activation Variables
-
-No activation variables required. Authentication is handled via Versori connection (`fluent_commerce`).
-
-**Note:** Configure Fluent Commerce credentials in the Versori connection settings. The connection handles authentication automatically.
-
-### Webhook Connection
-
-Create a Versori connection for webhook authentication:
-
-1. **Connection Name:** `order-update-webhook`
-2. **Type:** API Key or Basic Auth
-3. **Purpose:** Authenticate incoming webhook requests
-
-**Example webhook call:**
-
-```bash
-curl -X POST https://{workspace}.versori.run/order-update \
-  -H "Content-Type: application/json" \
-  -H "X-API-Key: your-api-key" \
-  -d '{
-    "orderRef": "ORD-12345",
-    "externalOrderId": "EXT-123456789",
-    "customerNotes": "Please leave package at front door",
-    "priority": "high"
-  }'
-```
-
----
-
-## 6. Error Handling
-
-The template includes comprehensive error handling:
-
-### Payload Parsing Errors
-
-- **Empty payload:** Returns error response
-- **Invalid JSON:** Returns error with parse details
-- **Missing order reference:** Returns error with expected field name
-- **Missing attributes:** Returns error if no attributes provided
-
-### Order Query Errors
-
-- **Order not found:** Returns error with order reference
-- **GraphQL query errors:** Returns error with GraphQL error details
-
-### Mutation Errors
-
-- **GraphQL mutation errors:** Returns error with mutation error details
-- **No response data:** Returns error if mutation doesn't return order data
-
-### Response Format with FC Status Codes
-
-**Success Response (FC200):**
-```json
-{
-  "success": true,
-  "statusCode": "FC200",
-  "orderRef": "ORD-12345",
-  "orderId": "12345",
-  "attributesUpdated": 3,
-  "message": "Order attributes updated successfully"
-}
-```
-
-**Error Responses:**
-
-**FC400 - Bad Request (Non-retryable):**
-```json
-{
-  "success": false,
-  "statusCode": "FC400",
-  "retryable": false,
-  "error": "Bad request. Please verify payload and try again.",
-  "details": "Order reference (orderRef) is required in payload"
-}
-```
-
-**FC409 - Duplicate/Already Exists (Non-retryable):**
-```json
-{
-  "success": false,
-  "statusCode": "FC409",
-  "retryable": false,
-  "error": "Entity already exists. Duplicate request detected.",
-  "details": "Order with reference ORD-12345 already exists"
-}
-```
-
-**FC504 - Timeout (Retryable):**
-```json
-{
-  "success": false,
-  "statusCode": "FC504",
-  "retryable": true,
-  "error": "Request timeout. Please retry.",
-  "details": "GraphQL mutation timed out after 30 seconds"
-}
-```
-
----
-
-## 7. Testing
-
-### Test with cURL - Flat Key-Value Format
-
-```bash
-# Test order update webhook with flat key-value format
-curl -X POST https://{workspace}.versori.run/order-update \
-  -H "Content-Type: application/json" \
-  -H "X-API-Key: your-api-key" \
-  -d '{
-    "orderRef": "ORD-12345",
-    "externalOrderId": "EXT-123456789",
-    "customerNotes": "Please leave package at front door",
-    "priority": "high"
-  }'
-```
-
-### Test with JSON File
-
-**Create `order-update.json`:**
-```json
-{
-  "orderRef": "ORD-0017326966182",
-  "externalOrderId": "EXT-123456789",
-  "customerNotes": "Please leave package at front door",
-  "priority": "high"
-}
-```
-
-**Send with cURL:**
-```bash
-curl -X POST https://{workspace}.versori.run/order-update \
-  -H "Content-Type: application/json" \
-  -H "X-API-Key: your-api-key" \
-  -d @order-update.json
-```
-
-### Expected Success Response
-
-```json
-{
-  "success": true,
-  "statusCode": "FC200",
-  "orderRef": "ORD-12345",
-  "orderId": "12345",
-  "attributesUpdated": 1,
-  "message": "Order attributes updated successfully"
-}
-```
-
-**FC Status Code:** `FC200` - OK (Successfully - No further action needed)
-
-### Expected Error Responses
-
-**FC400 - Bad Request:**
-```json
-{
-  "success": false,
-  "statusCode": "FC400",
-  "retryable": false,
-  "error": "Bad request. Please verify payload and try again.",
-  "details": "Order not found: ORD-12345"
-}
-```
-
-**FC409 - Duplicate/Already Exists:**
-```json
-{
-  "success": false,
-  "statusCode": "FC409",
-  "retryable": false,
-  "error": "Entity already exists. Duplicate request detected.",
-  "details": "Order with reference ORD-12345 already exists"
-}
-```
-
-**FC504 - Timeout:**
-```json
-{
-  "success": false,
-  "statusCode": "FC504",
-  "retryable": true,
-  "error": "Request timeout. Please retry.",
-  "details": "GraphQL mutation timed out"
-}
-```
-
----
-
-## 8. Customization
-
-### Merge with Existing Attributes
-
-To merge new attributes with existing ones (instead of replacing):
-
-```typescript
-// In executeOrderUpdate function, after queryOrderByRef:
-const existingAttributes = order.attributes || [];
-const mergedAttributes = [
-  ...existingAttributes,
-  ...attributes, // New attributes override existing ones with same name
-];
-
-const updateVariables = {
-  input: {
-    id: order.id, // ✅ REQUIRED: Use ID from query result
-    attributes: mergedAttributes,
-  },
-};
-```
-
-### Custom Attribute Type Detection
-
-To customize how attribute types are detected from object format:
-
-```typescript
-function convertToAttributeInput(
-  attributes: OrderUpdatePayload['attributes']
-): AttributeInput[] {
-  // Add custom type detection logic
-  // e.g., detect dates, URLs, etc.
-}
-```
-
-### Additional Order Fields
-
-To update additional order fields (status, etc.):
-
-```typescript
-const updateVariables = {
-  input: {
-    id: order.id, // ✅ REQUIRED: Use ID from query result
-    status: payload.status, // Update status if provided
-    attributes: attributes,
-  },
-};
-```
-
----
-
-## Summary
-
-✅ **DO:**
-- Use Versori connection for Fluent Commerce credentials
-- Query order first to validate existence and get ID
-- Use `id` from query result in UpdateOrderInput (required field)
-- Handle both array and object attribute formats
-- Log all steps for debugging
-- Return clear error messages
-
-❌ **DON'T:**
-- Hardcode credentials in code
-- Skip order query validation
-- Use `ref` in UpdateOrderInput (must use `id: ID!`)
-- Assume payload format without validation
-- Skip error handling
-
----
-
-## Next Steps
-
-1. **Deploy:** Copy code to your Versori project
-2. **Configure:** Set up Fluent Commerce connection and activation variables
-3. **Test:** Test webhook with sample payloads
-4. **Monitor:** Check Versori logs for order updates
-
-For more templates, see:
-- [XML Payload Template](./template-ingestion-payload-xml-order-update-graphql.md)
-- [Other GraphQL Mutation Templates](./graphql-mutations-guide.md)
-
+---
+template_id: tpl-ingest-payload-json-to-order-update-graphql
+canonical_filename: template-ingestion-payload-json-order-update-graphql.md
+sdk_version: latest
+runtime: versori
+direction: ingestion
+source: payload-json
+destination: fluent-graphql
+entity: order
+format: json
+logging: versori
+status: stable
+features:
+  - direct-payload-processing
+  - json-parsing
+  - graphql-mutations
+  - order-query-before-update
+  - attribute-updates
+---
+
+# Template: Ingestion - Payload JSON to Order Update GraphQL
+
+**SDK Version:** @fluentcommerce/fc-connect-sdk@latest
+**Last Updated:** 2025-01-24
+**Deployment Target:** Versori Platform
+
+---
+
+## 📋 Implementation Prompt
+
+```
+I need a Versori webhook ingestion that:
+
+1) Receives JSON payload directly in webhook request body with orderRef and attributes
+2) Parses JSON to extract order reference and attributes
+3) Queries Fluent Commerce to get order ID by order reference
+4) Updates order attributes using updateOrder GraphQL mutation
+5) Returns success/error response
+6) Uses native Versori log from context
+
+Use the loaded docs to fill in SDK specifics and best practices.
+Keep the structure identical to the template; only adapt where needed.
+```
+
+---
+
+## 📋 Template Overview
+
+This connector runs on the Versori platform. It receives JSON payloads directly via webhook with order reference and attributes, queries Fluent Commerce to get the order ID, and updates order attributes using GraphQL mutations. Most operational settings (Fluent account/connection) are configured via activation variables.
+
+### What This Template Does
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│          INGESTION WORKFLOW              │
+└────────────────────────────────────────────────────────────────┘
+
+1. TRIGGER
+  └─ Webhook: HTTP POST endpoint receives JSON payload
+
+2. RECEIVE PAYLOAD
+  ├─ Extract JSON from request body (ctx.data or ctx.request)
+  ├─ Validate payload structure
+  └─ Log incoming request
+
+3. PARSE JSON
+  ├─ Parse JSON payload (if raw string)
+  ├─ Extract order reference
+  ├─ Extract attributes array
+  └─ Validate required fields
+
+4. QUERY ORDER
+  ├─ Query Fluent Commerce: order(ref: orderRef)
+  ├─ Get order ID and current state
+  ├─ Validate order exists
+  └─ Log order details
+
+5. BUILD UPDATE MUTATION
+  ├─ Construct UpdateOrderInput with ref
+  ├─ Map attributes to AttributeInput format
+  ├─ Preserve existing attributes (optional merge)
+  └─ Build GraphQL mutation variables
+
+6. EXECUTE MUTATION
+  ├─ Execute updateOrder GraphQL mutation
+  ├─ Handle success/error responses
+  └─ Log mutation result
+
+7. RETURN RESPONSE
+  ├─ Return success with order details
+  └─ Return error with details if failed
+```
+
+### Key Features
+
+- **Direct Payload Processing**: Receives JSON payload directly in webhook request body
+- **Order Query First**: Queries order by ref to get ID and validate existence
+- **GraphQL Mutation**: Uses updateOrder mutation to update attributes
+- **Attribute Mapping**: Converts payload attributes to Fluent AttributeInput format
+- **Error Handling**: Comprehensive error handling with detailed logging
+- **Native Versori Logging**: Uses Versori log from context
+
+### 📦 Package Information
+
+**SDK:** [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk) `latest`
+
+```bash
+npm install @fluentcommerce/fc-connect-sdk@latest
+```
+
+---
+
+**Templates are designed for direct deployment; customize via activation variables.**
+
+---
+
+## 📦 SDK Imports (Verified - Versori Optimized)
+
+```typescript
+// ✅ VERIFIED IMPORTS - These match actual SDK exports
+import { Buffer } from 'node:buffer'; // Required for Versori/Deno runtime
+import {
+  createClient, // Universal client factory
+  JSONParserService, // JSON parsing utility
+} from '@fluentcommerce/fc-connect-sdk';
+
+import type { FluentClient } from '@fluentcommerce/fc-connect-sdk';
+
+// Versori platform imports
+import { webhook, http } from '@versori/run';
+```
+
+**Note:** All imports are from actual SDK exports - this code compiles and runs as-is.
+
+**⚠️ CRITICAL - Buffer Import Required:**
+
+The `Buffer` import from `node:buffer` is **required** for Versori/Deno runtime compatibility:
+- Versori and Deno do NOT have `Buffer` as a global (unlike Node.js)
+- Without this import, code will crash with `ReferenceError: Buffer is not defined`
+- Always include this import in Versori templates, even if not directly used in the template code
+- Required for SDK internal operations and any Buffer usage in your code
+
+**✅ VERSORI PLATFORM - Use Native Logs:**
+
+- Use `log` from context: `const { log } = ctx;`
+- Native Versori logs are simpler and automatically integrated with platform monitoring
+
+---
+
+## 🔐 Fluent Commerce Connection Setup
+
+**✅ BEST PRACTICE:** Store Fluent Commerce credentials in a Versori connection object:
+
+**Connection Configuration:**
+
+1. **Create Connection in Versori:**
+   - Name: `fluent_commerce`
+   - Type: HTTP Basic Auth or OAuth2
+   - Credentials: Fluent Commerce API credentials
+
+2. **Connection Variables:**
+   - `FLUENT_BASE_URL` - Fluent Commerce API base URL (e.g., `https://api.fluentcommerce.com`)
+   - `FLUENT_CLIENT_ID` - OAuth client ID (if using OAuth2)
+   - `FLUENT_CLIENT_SECRET` - OAuth client secret (if using OAuth2)
+   - `FLUENT_USERNAME` - Username (if using Basic Auth)
+   - `FLUENT_PASSWORD` - Password (if using Basic Auth)
+
+**Benefits:**
+- ✅ Credentials stored securely in Versori vault
+- ✅ Connection can be reused across workflows
+- ✅ No sensitive data in activation variables
+- ✅ Easier credential rotation
+
+---
+
+## 📄 Expected JSON Payload Format
+
+The webhook accepts **flat key-value JSON payloads**. All fields except `orderRef` are automatically treated as order attributes.
+
+### ✅ PRIMARY FORMAT: Flat Key-Value Pairs (Recommended)
+
+**Simple format - just key-value pairs, no nested structure:**
+
+```json
+{
+  "orderRef": "ORD-12345",
+  "externalOrderId": "EXT-123456789",
+  "customerNotes": "Please leave package at front door",
+  "priority": "high",
+  "tags": "rush,gift"
+}
+```
+
+**Type Auto-Detection:**
+- Numbers → `INTEGER` or `FLOAT` (auto-detected)
+- Booleans → `BOOLEAN` (auto-detected)
+- Objects → `JSON` (stringified)
+- Strings → `STRING` (default)
+
+**cURL Example:**
+```bash
+curl -X POST https://{workspace}.versori.run/order-update \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: your-api-key" \
+  -d '{
+    "orderRef": "ORD-12345",
+    "externalOrderId": "EXT-123456789",
+    "customerNotes": "Please leave package at front door",
+    "priority": "high"
+  }'
+```
+
+### Complete Sample Payloads
+
+**Example 1: External System Reference Update**
+```json
+{
+  "orderRef": "ORD-0017326966182",
+  "externalOrderId": "EXT-123456789",
+  "sourceSystem": "ERP-SAP",
+  "integrationId": "INT-987654321"
+}
+```
+
+**Example 2: Customer Notes and Business Flags**
+```json
+{
+  "orderRef": "ORD-0017326966182",
+  "customerNotes": "Please leave package at front door",
+  "priority": "high",
+  "tags": "rush,gift",
+  "specialHandling": true
+}
+```
+
+**Note:** Metadata fields (`updateReason`, `updatedBy`, `timestamp`) are optional and excluded from attributes. All other fields are treated as order attributes.
+
+---
+
+## GraphQL Mutations
+
+### Query Order by Reference
+
+```graphql
+query GetOrder($ref: String!) {
+  order(ref: $ref) {
+    id
+    ref
+    status
+    attributes {
+      name
+      type
+      value
+    }
+  }
+}
+```
+
+### Update Order Mutation
+
+```graphql
+mutation UpdateOrder($input: UpdateOrderInput!) {
+  updateOrder(input: $input) {
+    id
+    ref
+    status
+    attributes {
+      name
+      type
+      value
+    }
+  }
+}
+```
+
+**UpdateOrderInput Structure:**
+- `id` (ID!) - Order ID (required) - Must use Fluent internal ID, not reference
+- `attributes` (Array<AttributeInput>) - Attributes to update
+- `status` (String) - Optional status update
+- Other optional fields as per schema
+
+**Note:** UpdateOrderInput requires `id: ID!` (the Fluent internal ID), not `ref`. This is why the template queries the order first to get the ID.
+
+**AttributeInput Structure:**
+- `name` (String!) - Attribute name
+- `type` (String!) - Attribute type (STRING, INTEGER, FLOAT, BOOLEAN, JSON, DATE)
+- `value` (String!) - Attribute value (stringified for non-STRING types)
+
+---
+
+## 🔧 Complete Production Code
+
+### Versori Workflows Structure
+
+**Key Concept**: Versori workflows are organized by **trigger type** at the first level, then by **specific workflow** with descriptive file names.
+
+**Trigger Types:**
+- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
+
+**Execution Steps (chained to triggers):**
+- **`http()`** → External API calls (chained from webhook)
+
+### Recommended Project Structure
+
+```
+order-update-webhook/
+├── index.ts                              # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   └── webhook/
+    │       └── order-update.ts           # Webhook: Order update handler
+    │
+    ├── services/
+    │   └── order-update.service.ts       # Shared orchestration logic
+    │
+    ├── utils/
+    │   └── response-status.utils.ts      # FC status code mapping utilities
+    │
+    └── types/
+        └── order-update.types.ts         # Type definitions
+```
+
+**Benefits:**
+- ✅ Clear structure (webhook handlers in `webhook/`)
+- ✅ Descriptive file names (easy to browse and understand)
+- ✅ Reusable code in `services/` (DRY principle)
+- ✅ Centralized type definitions
+- ✅ Utility functions for consistent error handling (FC status codes)
+
+---
+
+## Workflow Files
+
+### 1. Webhook Workflow (`src/workflows/webhook/order-update.ts`)
+
+**Purpose**: Handle order update requests via webhook
+**Trigger**: HTTP POST
+**Endpoint**: `POST https://{workspace}.versori.run/order-update`
+**Use Cases**: Order attribute updates from external systems, status changes
+
+```typescript
+import { webhook, http } from '@versori/run';
+import { executeOrderUpdate } from '../../services/order-update.service';
+import { mapErrorToFCStatus } from '../../utils/response-status.utils';
+
+/**
+ * Webhook: Order Update Handler
+ *
+ * Endpoint: POST https://{workspace}.versori.run/order-update
+ * Request body: { "orderRef": "ORD-12345", "externalOrderId": "EXT-123", "customerNotes": "...", ... }
+ *
+ * Pattern: webhook().then(http()) - needs Fluent API access
+ * Uses shared service: order-update.service.ts
+ *
+ * SECURITY: Authentication handled via connection parameter
+ * No manual API key validation needed - Versori manages this via connection auth
+ */
+export const orderUpdateWebhook = webhook('order-update', {
+  response: { mode: 'sync' }, // ✅ Sync mode: response sent when handler returns
+  connection: 'order-update-webhook', // Versori validates API key
+}).then(
+  http('process-order-update', { connection: 'fluent_commerce' }, async ctx => {
+    const { log, data } = ctx;
+
+    log.info('🚀 [WEBHOOK] Order update request received', {
+      timestamp: new Date().toISOString(),
+      hasPayload: !!data,
+    });
+
+    try {
+      // Reuse shared orchestration logic
+      const result = await executeOrderUpdate(ctx);
+
+      log.info('✅ [WEBHOOK] Order update completed successfully', {
+        orderRef: result.orderRef,
+        orderId: result.orderId,
+        attributesUpdated: result.attributesUpdated,
+      });
+
+      // Return response with FC200 status code
+      return {
+        success: true,
+        statusCode: result.statusCode,
+        orderRef: result.orderRef,
+        orderId: result.orderId,
+        attributesUpdated: result.attributesUpdated,
+        message: result.message || 'Order attributes updated successfully',
+      };
+    } catch (e: any) {
+      log.error('❌ [WEBHOOK] Order update failed', {
+        message: e?.message,
+        stack: e?.stack,
+      });
+
+      // Map error to FC status code
+      const fcStatus = mapErrorToFCStatus(e);
+
+      return {
+        success: false,
+        statusCode: fcStatus.statusCode,
+        retryable: fcStatus.retryable,
+        error: fcStatus.message,
+        details: e?.message || 'Unknown error occurred',
+      };
+    }
+  })
+);
+```
+
+---
+
+### 2. Entry Point (`index.ts`)
+
+**Purpose**: Register all workflows with Versori platform
+
+```typescript
+/**
+ * Entry Point - Registers all workflows with Versori platform
+ *
+ * Versori automatically discovers and registers exported workflows
+ *
+ * File Structure:
+ * - src/workflows/webhook/   → HTTP-based triggers (webhooks)
+ * - src/services/            → Shared service logic (reusable across workflows)
+ */
+
+// Import webhook workflows
+import { orderUpdateWebhook } from './src/workflows/webhook/order-update';
+
+// Register all workflows with Versori platform
+export {
+  // Webhooks (HTTP-based triggers)
+  orderUpdateWebhook,
+};
+```
+
+**What Gets Exposed:**
+- ✅ `orderUpdateWebhook` → `https://{workspace}.versori.run/order-update`
+
+---
+
+## 3. Type Definitions (`src/types/order-update.types.ts`)
+
+```typescript
+/**
+ * Type Definitions for Order Update Ingestion
+ *
+ * Centralized type definitions for order update workflow
+ */
+
+/**
+ * Order update request payload
+ *
+ * PRIMARY FORMAT: Flat key-value pairs
+ * - orderRef: Required order reference
+ * - All other fields (except metadata fields) are treated as attributes
+ *
+ * Example:
+ * {
+ *   "orderRef": "ORD-12345",
+ *   "externalOrderId": "EXT-123456789",
+ *   "customerNotes": "Please leave package at front door",
+ *   "priority": "high"
+ * }
+ */
+export interface OrderUpdatePayload {
+  orderRef: string;
+  // Flat attributes: all fields except orderRef are treated as attributes
+  [key: string]: string | number | boolean | unknown;
+}
+
+/**
+ * Fluent AttributeInput format
+ */
+export interface AttributeInput {
+  name: string;
+  type: 'STRING' | 'INTEGER' | 'FLOAT' | 'BOOLEAN' | 'JSON' | 'DATE';
+  value: string;
+}
+
+/**
+ * Order query result
+ */
+export interface OrderQueryResult {
+  id: string;
+  ref: string;
+  status?: string;
+  attributes?: Array<{
+    name: string;
+    type: string;
+    value: string;
+  }>;
+}
+
+/**
+ * Order update result with FC status code
+ */
+export interface OrderUpdateResult {
+  success: boolean;
+  statusCode: 'FC200' | 'FC400' | 'FC409' | 'FC504';
+  orderRef: string;
+  orderId: string;
+  attributesUpdated: number;
+  message?: string;
+  error?: string;
+  retryable?: boolean;
+}
+
+/**
+ * Versori Context Interface
+ * Represents the Versori runtime context passed to workflow functions
+ */
+export interface VersoriContext {
+  log: {
+    info: (message: string, data?: Record<string, unknown>) => void;
+    warn: (message: string, data?: Record<string, unknown>) => void;
+    error: (message: string, data?: Record<string, unknown>) => void;
+    debug?: (message: string, data?: Record<string, unknown>) => void;
+  };
+  data?: unknown;
+  request?: Request;
+  activation: {
+    getVariable: (name: string) => string | undefined;
+    connections?: Record<string, unknown>;
+  };
+  connections?: Record<string, unknown>;
+}
+```
+
+---
+
+## 4. Utility: Response Status Code Mapper (`src/utils/response-status.utils.ts`)
+
+```typescript
+/**
+ * Response Status Code Utility
+ *
+ * Maps errors to Fluent Commerce (FC) status codes for consistent API responses
+ */
+
+/**
+ * FC Status Codes:
+ * - FC200: OK (Successfully - No further action needed)
+ * - FC400: Bad Request (Non-retryable)
+ * - FC409: Duplicate Request, Entity already exists (Non-retryable)
+ * - FC504: Timeout (Retryable)
+ */
+
+export type FCStatusCode = 'FC200' | 'FC400' | 'FC409' | 'FC504';
+
+export interface FCStatusMapping {
+  statusCode: FCStatusCode;
+  retryable: boolean;
+  message: string;
+}
+
+/**
+ * Map error to FC status code based on error message and type
+ */
+export function mapErrorToFCStatus(error: unknown): FCStatusMapping {
+  const errorMessage =
+    error instanceof Error ? error.message : String(error);
+  const lowerMessage = errorMessage.toLowerCase();
+
+  // FC409: Duplicate/Already exists (Non-retryable)
+  if (
+    lowerMessage.includes('already exists') ||
+    lowerMessage.includes('duplicate') ||
+    lowerMessage.includes('unique constraint') ||
+    lowerMessage.includes('entity already exists')
+  ) {
+    return {
+      statusCode: 'FC409',
+      retryable: false,
+      message: 'Entity already exists. Duplicate request detected.',
+    };
+  }
+
+  // FC504: Timeout (Retryable)
+  if (
+    lowerMessage.includes('timeout') ||
+    lowerMessage.includes('timed out') ||
+    lowerMessage.includes('request timeout') ||
+    (error instanceof Error && error.name === 'TimeoutError')
+  ) {
+    return {
+      statusCode: 'FC504',
+      retryable: true,
+      message: 'Request timeout. Please retry.',
+    };
+  }
+
+  // FC400: Bad Request (Non-retryable)
+  // Validation errors, missing fields, invalid format
+  if (
+    lowerMessage.includes('required') ||
+    lowerMessage.includes('missing') ||
+    lowerMessage.includes('invalid') ||
+    lowerMessage.includes('bad request') ||
+    lowerMessage.includes('validation') ||
+    lowerMessage.includes('not found') ||
+    lowerMessage.includes('does not exist')
+  ) {
+    return {
+      statusCode: 'FC400',
+      retryable: false,
+      message: 'Bad request. Please verify payload and try again.',
+    };
+  }
+
+  // Default: FC400 for unknown errors (Non-retryable)
+  return {
+    statusCode: 'FC400',
+    retryable: false,
+    message: errorMessage,
+  };
+}
+
+/**
+ * Create success response with FC200 status
+ */
+export function createSuccessResponse<T extends Record<string, unknown>>(
+  data: T
+): T & { statusCode: 'FC200'; retryable: false } {
+  return {
+    ...data,
+    statusCode: 'FC200' as const,
+    retryable: false,
+  };
+}
+```
+
+---
+
+## 5. Service: Order Update Processor (`src/services/order-update.service.ts`)
+
+```typescript
+/**
+ * Order Update Service
+ *
+ * Processes order update requests: extracts order reference and attributes from JSON payload,
+ * queries Fluent Commerce to get order ID, and updates order attributes via GraphQL mutation.
+ */
+
+import {
+  createClient,
+  JSONParserService,
+} from '@fluentcommerce/fc-connect-sdk';
+import { Buffer } from 'node:buffer';
+import { mapErrorToFCStatus, createSuccessResponse } from '../utils/response-status.utils';
+import type { FluentClient } from '@fluentcommerce/fc-connect-sdk';
+import type {
+  OrderUpdatePayload,
+  OrderUpdateResult,
+  VersoriContext,
+  AttributeInput,
+  OrderQueryResult,
+} from '../types/order-update.types';
+
+/**
+ * GraphQL query to get order by reference
+ */
+const GET_ORDER_QUERY = `
+  query GetOrder($ref: String!) {
+    order(ref: $ref) {
+      id
+      ref
+      status
+      attributes {
+        name
+        type
+        value
+      }
+    }
+  }
+`;
+
+/**
+ * GraphQL mutation to update order
+ */
+const UPDATE_ORDER_MUTATION = `
+  mutation UpdateOrder($input: UpdateOrderInput!) {
+    updateOrder(input: $input) {
+      id
+      ref
+      status
+      attributes {
+        name
+        type
+        value
+      }
+    }
+  }
+`;
+
+/**
+ * Extract attributes from flat payload format
+ *
+ * PRIMARY FORMAT: All fields except orderRef (and metadata fields) are attributes
+ * - orderRef: Required, excluded from attributes
+ * - Metadata fields: updateReason, updatedBy, timestamp (optional, excluded)
+ * - All other fields: Treated as attributes with auto-detected types
+ *
+ * Example payload:
+ * {
+ *   "orderRef": "ORD-12345",
+ *   "externalOrderId": "EXT-123456789",       // → attribute
+ *   "customerNotes": "Front door",            // → attribute
+ *   "priority": "high"                        // → attribute
+ * }
+ */
+function extractAttributesFromPayload(
+  payload: OrderUpdatePayload
+): AttributeInput[] {
+  const metadataFields = ['orderRef', 'updateReason', 'updatedBy', 'timestamp'];
+  const attributes: AttributeInput[] = [];
+
+  // Extract all fields except orderRef and metadata fields
+  for (const [name, value] of Object.entries(payload)) {
+    // Skip metadata fields
+    if (metadataFields.includes(name)) {
+      continue;
+    }
+
+    // Skip null/undefined values
+    if (value === null || value === undefined) {
+      continue;
+    }
+
+    // Auto-detect type from value
+    let type: AttributeInput['type'] = 'STRING';
+    let stringValue: string;
+
+    if (typeof value === 'number') {
+      type = Number.isInteger(value) ? 'INTEGER' : 'FLOAT';
+      stringValue = String(value);
+    } else if (typeof value === 'boolean') {
+      type = 'BOOLEAN';
+      stringValue = String(value);
+    } else if (typeof value === 'object') {
+      type = 'JSON';
+      stringValue = JSON.stringify(value);
+    } else {
+      // String or other types → STRING
+      stringValue = String(value);
+    }
+
+    attributes.push({
+      name,
+      type,
+      value: stringValue,
+    });
+  }
+
+  return attributes;
+}
+
+/**
+ * Parse webhook payload from Versori context
+ *
+ * Handles both pre-parsed JSON (ctx.data) and raw request body (ctx.request)
+ */
+async function parseWebhookPayload(
+  ctx: VersoriContext
+): Promise<OrderUpdatePayload | null> {
+  const { log, data, request } = ctx;
+
+  // Scenario 1: Pre-parsed JSON (Versori auto-parsed)
+  if (data && typeof data === 'object' && data !== null) {
+    log.info('📥 [PARSE] Using pre-parsed JSON payload', {
+      hasData: true,
+      dataKeys: Object.keys(data),
+    });
+    return data as OrderUpdatePayload;
+  }
+
+  // Scenario 2: Raw request body (need to parse)
+  if (request && typeof request.text === 'function') {
+    log.info('📥 [PARSE] Extracting raw request body');
+    try {
+      const rawBody = await request.text();
+      if (!rawBody || rawBody.trim() === '') {
+        log.error('❌ [PARSE] Request body is empty');
+        return null;
+      }
+
+      const parser = new JSONParserService(log);
+      const parsed = await parser.parse(rawBody);
+      
+      log.info('📥 [PARSE] Successfully parsed JSON payload', {
+        parsedKeys: Object.keys(parsed),
+      });
+      
+      return parsed as OrderUpdatePayload;
+    } catch (parseError: unknown) {
+      const errorMessage =
+        parseError instanceof Error ? parseError.message : String(parseError);
+      log.error('❌ [PARSE] Failed to parse JSON payload', {
+        error: errorMessage,
+      });
+      return null;
+    }
+  }
+
+  log.error('❌ [PARSE] No valid payload found in context');
+  return null;
+}
+
+/**
+ * Query order by reference to get ID and current state
+ */
+async function queryOrderByRef(
+  client: FluentClient,
+  orderRef: string,
+  log: VersoriContext['log']
+): Promise<OrderQueryResult> {
+  log.info('🔍 [QUERY] Querying order by reference', { orderRef });
+
+  const result = await client.graphql({
+    query: GET_ORDER_QUERY,
+    variables: { ref: orderRef },
+  });
+
+  if (result.errors && result.errors.length > 0) {
+    log.error('❌ [QUERY] GraphQL query returned errors', {
+      errors: result.errors,
+      orderRef,
+    });
+    throw new Error(`GraphQL query failed: ${result.errors[0].message}`);
+  }
+
+  const order = (result.data as any)?.order;
+
+  if (!order) {
+    log.error('❌ [QUERY] Order not found', { orderRef });
+    throw new Error(`Order not found: ${orderRef}`);
+  }
+
+  log.info('✅ [QUERY] Order found', {
+    orderId: order.id,
+    orderRef: order.ref,
+    status: order.status,
+    currentAttributeCount: order.attributes?.length || 0,
+  });
+
+  return order as OrderQueryResult;
+}
+
+/**
+ * Execute order update workflow
+ *
+ * Main orchestration function:
+ * 1. Parse webhook payload
+ * 2. Extract order reference and attributes
+ * 3. Create Fluent client
+ * 4. Query order by reference to get ID
+ * 5. Build update mutation variables
+ * 6. Execute updateOrder mutation
+ *
+ * Note: Authentication handled via Versori connection (fluent_commerce).
+ * Retailer ID is not required for GraphQL mutations - connection handles authentication.
+ *
+ * CRITICAL: UpdateOrderInput requires id: ID! (not ref).
+ * The query step retrieves order.id which must be used in the mutation.
+ */
+export async function executeOrderUpdate(
+  ctx: VersoriContext
+): Promise<OrderUpdateResult> {
+  const { log, activation } = ctx;
+
+  log.info('🚀 [SERVICE] Starting order update processing');
+
+  // STEP 1: Parse webhook payload
+  const payload = await parseWebhookPayload(ctx);
+  if (!payload) {
+    log.error('❌ [SERVICE] Failed to parse webhook payload', {
+      hasData: !!ctx.data,
+      hasRequest: !!ctx.request,
+    });
+    throw new Error('Failed to parse webhook payload. Ensure Content-Type: application/json is set in request headers.');
+  }
+
+  log.info('📥 [SERVICE] Payload parsed successfully', {
+    payloadKeys: Object.keys(payload),
+  });
+
+  // STEP 2: Extract order reference
+  if (!payload.orderRef || typeof payload.orderRef !== 'string') {
+    log.error('❌ [SERVICE] Order reference not found in payload', {
+      payloadKeys: Object.keys(payload),
+      expectedField: 'orderRef',
+    });
+    throw new Error('Order reference (orderRef) is required in payload');
+  }
+
+  const orderRef = payload.orderRef;
+  log.info('✅ [SERVICE] Order reference extracted', { orderRef });
+
+  // STEP 3: Extract attributes from flat payload format
+  // ✅ PRIMARY FORMAT: All fields except orderRef are treated as attributes
+  const attributes = extractAttributesFromPayload(payload);
+  if (attributes.length === 0) {
+    log.warn('⚠️ [SERVICE] No attributes provided in payload', {
+      orderRef,
+      payloadKeys: Object.keys(payload),
+    });
+    throw new Error('At least one attribute is required for order update. Provide fields like: { "orderRef": "ORD-123", "externalOrderId": "EXT-123", "customerNotes": "Leave at door" }');
+  }
+
+  log.info('✅ [SERVICE] Attributes extracted', {
+    orderRef,
+    attributeCount: attributes.length,
+    attributeNames: attributes.map(a => a.name),
+  });
+
+  // STEP 4: Create Fluent client
+  // ✅ Pass ctx directly - createClient auto-detects Versori context
+  // Authentication handled via Versori connection (fluent_commerce)
+  const client = await createClient(ctx);
+
+  log.info('✅ [SERVICE] Fluent client created');
+
+  // STEP 5: Query order by reference to get ID
+  // ✅ Query first to:
+  //    - Validate order exists (fail-fast if order not found)
+  //    - Get order ID for logging and tracking
+  //    - Get current order state (optional: can merge with existing attributes)
+  const order = await queryOrderByRef(client, orderRef, log);
+
+  // STEP 6: Build update mutation variables
+  // ✅ CRITICAL: UpdateOrderInput requires id: ID! (not ref)
+  //    Use the ID from queryOrderByRef result - this is why we query first!
+  const updateVariables = {
+    input: {
+      id: order.id, // ✅ REQUIRED: UpdateOrderInput.id is ID! (required field)
+      attributes: attributes,
+    },
+  };
+
+  log.info('📤 [SERVICE] Executing updateOrder mutation', {
+    orderRef,
+    orderId: order.id,
+    attributeCount: attributes.length,
+  });
+
+  // STEP 7: Execute updateOrder mutation
+  const mutationResult = await client.graphql({
+    query: UPDATE_ORDER_MUTATION,
+    variables: updateVariables,
+  });
+
+  if (mutationResult.errors && mutationResult.errors.length > 0) {
+    log.error('❌ [SERVICE] GraphQL mutation returned errors', {
+      errors: mutationResult.errors,
+      orderRef,
+      orderId: order.id,
+    });
+    throw new Error(`GraphQL mutation failed: ${mutationResult.errors[0].message}`);
+  }
+
+  const updatedOrder = (mutationResult.data as any)?.updateOrder;
+
+  if (!updatedOrder) {
+    log.error('❌ [SERVICE] No order data returned from mutation', { orderRef });
+    throw new Error('No order data returned from updateOrder mutation');
+  }
+
+  log.info('✅ [SERVICE] Order updated successfully', {
+    orderRef,
+    orderId: updatedOrder.id,
+    attributesUpdated: attributes.length,
+  });
+
+  // Return success response with FC200 status code
+  return createSuccessResponse({
+    success: true,
+    orderRef,
+    orderId: updatedOrder.id,
+    attributesUpdated: attributes.length,
+    message: 'Order attributes updated successfully',
+  });
+}
+```
+
+---
+
+## 5. Configuration
+
+### Activation Variables
+
+No activation variables required. Authentication is handled via Versori connection (`fluent_commerce`).
+
+**Note:** Configure Fluent Commerce credentials in the Versori connection settings. The connection handles authentication automatically.
+
+### Webhook Connection
+
+Create a Versori connection for webhook authentication:
+
+1. **Connection Name:** `order-update-webhook`
+2. **Type:** API Key or Basic Auth
+3. **Purpose:** Authenticate incoming webhook requests
+
+**Example webhook call:**
+
+```bash
+curl -X POST https://{workspace}.versori.run/order-update \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: your-api-key" \
+  -d '{
+    "orderRef": "ORD-12345",
+    "externalOrderId": "EXT-123456789",
+    "customerNotes": "Please leave package at front door",
+    "priority": "high"
+  }'
+```
+
+---
+
+## 6. Error Handling
+
+The template includes comprehensive error handling:
+
+### Payload Parsing Errors
+
+- **Empty payload:** Returns error response
+- **Invalid JSON:** Returns error with parse details
+- **Missing order reference:** Returns error with expected field name
+- **Missing attributes:** Returns error if no attributes provided
+
+### Order Query Errors
+
+- **Order not found:** Returns error with order reference
+- **GraphQL query errors:** Returns error with GraphQL error details
+
+### Mutation Errors
+
+- **GraphQL mutation errors:** Returns error with mutation error details
+- **No response data:** Returns error if mutation doesn't return order data
+
+### Response Format with FC Status Codes
+
+**Success Response (FC200):**
+```json
+{
+  "success": true,
+  "statusCode": "FC200",
+  "orderRef": "ORD-12345",
+  "orderId": "12345",
+  "attributesUpdated": 3,
+  "message": "Order attributes updated successfully"
+}
+```
+
+**Error Responses:**
+
+**FC400 - Bad Request (Non-retryable):**
+```json
+{
+  "success": false,
+  "statusCode": "FC400",
+  "retryable": false,
+  "error": "Bad request. Please verify payload and try again.",
+  "details": "Order reference (orderRef) is required in payload"
+}
+```
+
+**FC409 - Duplicate/Already Exists (Non-retryable):**
+```json
+{
+  "success": false,
+  "statusCode": "FC409",
+  "retryable": false,
+  "error": "Entity already exists. Duplicate request detected.",
+  "details": "Order with reference ORD-12345 already exists"
+}
+```
+
+**FC504 - Timeout (Retryable):**
+```json
+{
+  "success": false,
+  "statusCode": "FC504",
+  "retryable": true,
+  "error": "Request timeout. Please retry.",
+  "details": "GraphQL mutation timed out after 30 seconds"
+}
+```
+
+---
+
+## 7. Testing
+
+### Test with cURL - Flat Key-Value Format
+
+```bash
+# Test order update webhook with flat key-value format
+curl -X POST https://{workspace}.versori.run/order-update \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: your-api-key" \
+  -d '{
+    "orderRef": "ORD-12345",
+    "externalOrderId": "EXT-123456789",
+    "customerNotes": "Please leave package at front door",
+    "priority": "high"
+  }'
+```
+
+### Test with JSON File
+
+**Create `order-update.json`:**
+```json
+{
+  "orderRef": "ORD-0017326966182",
+  "externalOrderId": "EXT-123456789",
+  "customerNotes": "Please leave package at front door",
+  "priority": "high"
+}
+```
+
+**Send with cURL:**
+```bash
+curl -X POST https://{workspace}.versori.run/order-update \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: your-api-key" \
+  -d @order-update.json
+```
+
+### Expected Success Response
+
+```json
+{
+  "success": true,
+  "statusCode": "FC200",
+  "orderRef": "ORD-12345",
+  "orderId": "12345",
+  "attributesUpdated": 1,
+  "message": "Order attributes updated successfully"
+}
+```
+
+**FC Status Code:** `FC200` - OK (Successfully - No further action needed)
+
+### Expected Error Responses
+
+**FC400 - Bad Request:**
+```json
+{
+  "success": false,
+  "statusCode": "FC400",
+  "retryable": false,
+  "error": "Bad request. Please verify payload and try again.",
+  "details": "Order not found: ORD-12345"
+}
+```
+
+**FC409 - Duplicate/Already Exists:**
+```json
+{
+  "success": false,
+  "statusCode": "FC409",
+  "retryable": false,
+  "error": "Entity already exists. Duplicate request detected.",
+  "details": "Order with reference ORD-12345 already exists"
+}
+```
+
+**FC504 - Timeout:**
+```json
+{
+  "success": false,
+  "statusCode": "FC504",
+  "retryable": true,
+  "error": "Request timeout. Please retry.",
+  "details": "GraphQL mutation timed out"
+}
+```
+
+---
+
+## 8. Customization
+
+### Merge with Existing Attributes
+
+To merge new attributes with existing ones (instead of replacing):
+
+```typescript
+// In executeOrderUpdate function, after queryOrderByRef:
+const existingAttributes = order.attributes || [];
+const mergedAttributes = [
+  ...existingAttributes,
+  ...attributes, // New attributes override existing ones with same name
+];
+
+const updateVariables = {
+  input: {
+    id: order.id, // ✅ REQUIRED: Use ID from query result
+    attributes: mergedAttributes,
+  },
+};
+```
+
+### Custom Attribute Type Detection
+
+To customize how attribute types are detected from object format:
+
+```typescript
+function convertToAttributeInput(
+  attributes: OrderUpdatePayload['attributes']
+): AttributeInput[] {
+  // Add custom type detection logic
+  // e.g., detect dates, URLs, etc.
+}
+```
+
+### Additional Order Fields
+
+To update additional order fields (status, etc.):
+
+```typescript
+const updateVariables = {
+  input: {
+    id: order.id, // ✅ REQUIRED: Use ID from query result
+    status: payload.status, // Update status if provided
+    attributes: attributes,
+  },
+};
+```
+
+---
+
+## Summary
+
+✅ **DO:**
+- Use Versori connection for Fluent Commerce credentials
+- Query order first to validate existence and get ID
+- Use `id` from query result in UpdateOrderInput (required field)
+- Handle both array and object attribute formats
+- Log all steps for debugging
+- Return clear error messages
+
+❌ **DON'T:**
+- Hardcode credentials in code
+- Skip order query validation
+- Use `ref` in UpdateOrderInput (must use `id: ID!`)
+- Assume payload format without validation
+- Skip error handling
+
+---
+
+## Next Steps
+
+1. **Deploy:** Copy code to your Versori project
+2. **Configure:** Set up Fluent Commerce connection and activation variables
+3. **Test:** Test webhook with sample payloads
+4. **Monitor:** Check Versori logs for order updates
+
+For more templates, see:
+- [XML Payload Template](./template-ingestion-payload-xml-order-update-graphql.md)
+- [Other GraphQL Mutation Templates](./graphql-mutations-guide.md)
+