ERP & Procurement Integration

The ERP integration connects your ITSM Automation platform to enterprise resource planning and procurement systems — SAP S/4HANA, Oracle ERP, and manual procurement workflows. This enables automated purchase requisitions for hardware replacement, software license procurement, and cost tracking per ticket or project. When an agent resolves a ticket that requires a new asset, a procurement request can be created directly from the ticket context with pre-filled cost center and budget allocation.

The procurement request model

The procurement request model represents a purchase requisition flowing between ITSM and your ERP system. Each request tracks line items, approval status, vendor assignment, and the ERP purchase order once created.

Properties

Name
id
Type
string
Description
Unique identifier for the procurement request.
Name
type
Type
string
Description
The procurement type. One of hardware, software_license, service, or consumable.
Name
status
Type
string
Description
Current lifecycle status. One of draft, pending_approval, approved, ordered, received, or cancelled.
Name
title
Type
string
Description
Short summary of the procurement request.
Name
description
Type
string
Description
Detailed description of what is being procured and why.
Name
requester_id
Type
string
Description
The ID of the user who created the procurement request.
Name
approver_id
Type
string
Description
The ID of the manager or approver assigned to review this request.
Name
ticket_id
Type
string
Description
The ID of the related ITSM ticket, if the request was created from a ticket context.
Name
items
Type
array
Description
Line items for the procurement request. Each item contains name (string), sku (string), quantity (integer), unit_cost (number), and currency (string).
Name
total_cost
Type
number
Description
Computed total cost across all line items.
Name
currency
Type
string
Description
ISO 4217 currency code (e.g., USD, EUR, GBP).
Name
vendor
Type
string
Description
The vendor name assigned to fulfill this request.
Name
erp_source
Type
string
Description
The ERP system this request is synced with. One of sap_s4hana, oracle_erp, or manual.
Name
erp_po_number
Type
string
Description
The purchase order number assigned by the ERP system once the order is placed.
Name
cost_center
Type
string
Description
The cost center code charged for this procurement (e.g., CC-IT-OPS).
Name
budget_code
Type
string
Description
The budget line code for financial tracking.
Name
expected_delivery
Type
string
Description
Expected delivery date in ISO 8601 format.
Name
created_at
Type
timestamp
Description
Timestamp of when the procurement request was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the procurement request was last updated.
Name
org_id
Type
string
Description
The tenant organization ID that owns this procurement request.

GET/v1/erp/procurement

List procurement requests

This endpoint returns a paginated list of procurement requests for your organization. You can filter by status, type, and requester. Results are ordered by created_at descending (most recent first).

Optional attributes

Name
status
Type
string
Description
Filter by request status: draft, pending_approval, approved, ordered, received, or cancelled.
Name
type
Type
string
Description
Filter by procurement type: hardware, software_license, service, or consumable.
Name
requester_id
Type
string
Description
Filter by the user who created the request.
Name
limit
Type
integer
Description
Limit the number of results returned. Default is 20, maximum is 100.

Request

GET

/v1/erp/procurement

curl -G http://localhost:3000/v1/erp/procurement \
  -H "Authorization: Bearer {token}" \
  -d status=pending_approval \
  -d type=hardware \
  -d limit=10

Response

{
  "has_more": true,
  "data": [
    {
      "id": "proc_9xKpQ2mR4wVbN3",
      "type": "hardware",
      "status": "pending_approval",
      "title": "Laptop Replacement — Water Damage",
      "description": "Replacement laptop for employee after liquid damage to current device. Original ticket INC-00847.",
      "requester_id": "usr_7nLsW8kF9xYt",
      "approver_id": "usr_3kPmN8rT2wXq",
      "ticket_id": "tkt_4kPmN8rT2wXq",
      "items": [
        {
          "name": "Dell Latitude 5550 Laptop",
          "sku": "DELL-LAT5550-i7-16",
          "quantity": 1,
          "unit_cost": 1429.00,
          "currency": "USD"
        },
        {
          "name": "Dell WD22TB4 Thunderbolt Dock",
          "sku": "DELL-WD22TB4",
          "quantity": 1,
          "unit_cost": 279.00,
          "currency": "USD"
        }
      ],
      "total_cost": 1708.00,
      "currency": "USD",
      "vendor": "Dell Technologies",
      "erp_source": "sap_s4hana",
      "erp_po_number": null,
      "cost_center": "CC-IT-EUS",
      "budget_code": "BUD-2026-HW-Q1",
      "expected_delivery": "2026-03-10",
      "created_at": 1708732800,
      "updated_at": 1708732800,
      "org_id": "org_5jHtK4pR8uWn"
    },
    {
      "id": "proc_3nLsW8kF9xYtP7",
      "type": "software_license",
      "status": "pending_approval",
      "title": "JetBrains IntelliJ IDEA Licenses",
      "description": "Annual license renewal for the platform engineering team — 8 seats.",
      "requester_id": "usr_8mWqR3nT5vXp",
      "approver_id": "usr_3kPmN8rT2wXq",
      "ticket_id": null,
      "items": [
        {
          "name": "IntelliJ IDEA Ultimate — Annual",
          "sku": "JB-IDEA-ULT-ANN",
          "quantity": 8,
          "unit_cost": 599.00,
          "currency": "USD"
        }
      ],
      "total_cost": 4792.00,
      "currency": "USD",
      "vendor": "JetBrains",
      "erp_source": "sap_s4hana",
      "erp_po_number": null,
      "cost_center": "CC-IT-DEV",
      "budget_code": "BUD-2026-SW-Q1",
      "expected_delivery": "2026-03-01",
      "created_at": 1708732500,
      "updated_at": 1708732500,
      "org_id": "org_5jHtK4pR8uWn"
    }
  ]
}

POST/v1/erp/procurement

Create a procurement request

This endpoint creates a new procurement request. If a ticket_id is provided, the request is linked to the ITSM ticket and the ticket timeline is updated with the procurement reference. The request starts in draft status unless submit is set to true, in which case it moves directly to pending_approval.

Required attributes

Name
type
Type
string
Description
The procurement type: hardware, software_license, service, or consumable.
Name
title
Type
string
Description
Short summary of the procurement request.
Name
items
Type
array
Description
Line items with name, sku, quantity, unit_cost, and currency.
Name
cost_center
Type
string
Description
The cost center code to charge (e.g., CC-IT-OPS).

Optional attributes

Name
description
Type
string
Description
Detailed description of the procurement need.
Name
ticket_id
Type
string
Description
Link this request to an existing ITSM ticket.
Name
vendor
Type
string
Description
Preferred vendor name.
Name
budget_code
Type
string
Description
Budget line code for financial tracking.
Name
expected_delivery
Type
string
Description
Requested delivery date in ISO 8601 format.
Name
submit
Type
boolean
Description
When true, immediately submits for approval instead of saving as draft. Defaults to false.

Request

POST

/v1/erp/procurement

curl -X POST http://localhost:3000/v1/erp/procurement \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "hardware",
    "title": "Replacement Server — Rack Unit 14",
    "description": "Replace failed HPE ProLiant DL380 in rack 14. Original incident INC-01203.",
    "ticket_id": "tkt_6jHtK4pR8uWn",
    "items": [
      {
        "name": "HPE ProLiant DL380 Gen11",
        "sku": "HPE-DL380-G11-2P",
        "quantity": 1,
        "unit_cost": 8750.00,
        "currency": "USD"
      },
      {
        "name": "HPE 32GB DDR5 RDIMM",
        "sku": "HPE-DDR5-32G-RD",
        "quantity": 4,
        "unit_cost": 189.00,
        "currency": "USD"
      },
      {
        "name": "HPE 1.92TB SAS SSD",
        "sku": "HPE-SSD-192T-SAS",
        "quantity": 6,
        "unit_cost": 425.00,
        "currency": "USD"
      }
    ],
    "vendor": "Hewlett Packard Enterprise",
    "cost_center": "CC-IT-INFRA",
    "budget_code": "BUD-2026-HW-INFRA-Q1",
    "expected_delivery": "2026-03-15",
    "submit": true
  }'

Response

{
  "id": "proc_5pRtH5jN2cEmK8",
  "type": "hardware",
  "status": "pending_approval",
  "title": "Replacement Server — Rack Unit 14",
  "description": "Replace failed HPE ProLiant DL380 in rack 14. Original incident INC-01203.",
  "requester_id": "usr_2kNpL7mS9wYr",
  "approver_id": "usr_3kPmN8rT2wXq",
  "ticket_id": "tkt_6jHtK4pR8uWn",
  "items": [
    { "name": "HPE ProLiant DL380 Gen11", "sku": "HPE-DL380-G11-2P", "quantity": 1, "unit_cost": 8750.00, "currency": "USD" },
    { "name": "HPE 32GB DDR5 RDIMM", "sku": "HPE-DDR5-32G-RD", "quantity": 4, "unit_cost": 189.00, "currency": "USD" },
    { "name": "HPE 1.92TB SAS SSD", "sku": "HPE-SSD-192T-SAS", "quantity": 6, "unit_cost": 425.00, "currency": "USD" }
  ],
  "total_cost": 12056.00,
  "currency": "USD",
  "vendor": "Hewlett Packard Enterprise",
  "erp_source": "sap_s4hana",
  "erp_po_number": null,
  "cost_center": "CC-IT-INFRA",
  "budget_code": "BUD-2026-HW-INFRA-Q1",
  "expected_delivery": "2026-03-15",
  "created_at": 1708733400,
  "updated_at": 1708733400,
  "org_id": "org_5jHtK4pR8uWn"
}

GET/v1/erp/procurement/:id

Get procurement request

This endpoint retrieves the full details of a single procurement request, including all line items, approval history, and the ERP purchase order reference if the order has been placed.

Request

GET

/v1/erp/procurement/proc_9xKpQ2mR4wVbN3

curl http://localhost:3000/v1/erp/procurement/proc_9xKpQ2mR4wVbN3 \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "proc_9xKpQ2mR4wVbN3",
  "type": "hardware",
  "status": "ordered",
  "title": "Laptop Replacement — Water Damage",
  "description": "Replacement laptop for employee after liquid damage to current device. Original ticket INC-00847.",
  "requester_id": "usr_7nLsW8kF9xYt",
  "approver_id": "usr_3kPmN8rT2wXq",
  "ticket_id": "tkt_4kPmN8rT2wXq",
  "items": [
    { "name": "Dell Latitude 5550 Laptop", "sku": "DELL-LAT5550-i7-16", "quantity": 1, "unit_cost": 1429.00, "currency": "USD" },
    { "name": "Dell WD22TB4 Thunderbolt Dock", "sku": "DELL-WD22TB4", "quantity": 1, "unit_cost": 279.00, "currency": "USD" }
  ],
  "total_cost": 1708.00,
  "currency": "USD",
  "vendor": "Dell Technologies",
  "erp_source": "sap_s4hana",
  "erp_po_number": "PO-4500012847",
  "cost_center": "CC-IT-EUS",
  "budget_code": "BUD-2026-HW-Q1",
  "expected_delivery": "2026-03-10",
  "approval_history": [
    {
      "action": "submitted",
      "by": "usr_7nLsW8kF9xYt",
      "at": 1708732800,
      "comment": null
    },
    {
      "action": "approved",
      "by": "usr_3kPmN8rT2wXq",
      "at": 1708733100,
      "comment": "Approved — within quarterly hardware budget."
    }
  ],
  "created_at": 1708732800,
  "updated_at": 1708734000,
  "org_id": "org_5jHtK4pR8uWn"
}

PATCH/v1/erp/procurement/:id

Update a procurement request

This endpoint updates an existing procurement request. Only requests in draft or pending_approval status can be updated. Once a request is approved or ordered, it becomes immutable — create a new request or contact the approver to revert the status.

Optional attributes

Name
title
Type
string
Description
Updated title for the procurement request.
Name
description
Type
string
Description
Updated description.
Name
items
Type
array
Description
Replacement line items array. Replaces all existing items.
Name
vendor
Type
string
Description
Updated vendor name.
Name
cost_center
Type
string
Description
Updated cost center code.
Name
budget_code
Type
string
Description
Updated budget line code.
Name
expected_delivery
Type
string
Description
Updated expected delivery date.

Request

PATCH

/v1/erp/procurement/proc_3nLsW8kF9xYtP7

curl -X PATCH http://localhost:3000/v1/erp/procurement/proc_3nLsW8kF9xYtP7 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "name": "IntelliJ IDEA Ultimate — Annual",
        "sku": "JB-IDEA-ULT-ANN",
        "quantity": 10,
        "unit_cost": 599.00,
        "currency": "USD"
      }
    ],
    "description": "Annual license renewal for platform engineering and QA teams — increased to 10 seats."
  }'

Response

{
  "id": "proc_3nLsW8kF9xYtP7",
  "type": "software_license",
  "status": "pending_approval",
  "title": "JetBrains IntelliJ IDEA Licenses",
  "description": "Annual license renewal for platform engineering and QA teams — increased to 10 seats.",
  "items": [
    { "name": "IntelliJ IDEA Ultimate — Annual", "sku": "JB-IDEA-ULT-ANN", "quantity": 10, "unit_cost": 599.00, "currency": "USD" }
  ],
  "total_cost": 5990.00,
  "currency": "USD",
  "vendor": "JetBrains",
  "erp_source": "sap_s4hana",
  "erp_po_number": null,
  "cost_center": "CC-IT-DEV",
  "budget_code": "BUD-2026-SW-Q1",
  "expected_delivery": "2026-03-01",
  "created_at": 1708732500,
  "updated_at": 1708733600,
  "org_id": "org_5jHtK4pR8uWn"
}

POST/v1/erp/procurement/:id/approve

Approve a procurement request

This endpoint approves a procurement request. Only users with the procurement_approver role and requests in pending_approval status can be approved. Once approved, the request is automatically synced to the configured ERP system to generate a purchase order.

Optional attributes

Name
comment
Type
string
Description
Approval comment for the audit trail.

Request

POST

/v1/erp/procurement/proc_9xKpQ2mR4wVbN3/approve

curl -X POST http://localhost:3000/v1/erp/procurement/proc_9xKpQ2mR4wVbN3/approve \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Approved — within quarterly hardware budget. Expedite delivery if possible."
  }'

Response

{
  "id": "proc_9xKpQ2mR4wVbN3",
  "status": "approved",
  "approved_by": "usr_3kPmN8rT2wXq",
  "approved_at": 1708733100,
  "comment": "Approved — within quarterly hardware budget. Expedite delivery if possible.",
  "erp_sync_status": "queued",
  "erp_sync_job_id": "sync_8mWqR3nT5vXp"
}

POST/v1/erp/procurement/:id/reject

Reject a procurement request

This endpoint rejects a procurement request. The requester is notified and the request moves to cancelled status. A rejection reason is required for audit compliance.

Required attributes

Name
reason
Type
string
Description
The reason for rejecting the procurement request.

Request

POST

/v1/erp/procurement/proc_3nLsW8kF9xYtP7/reject

curl -X POST http://localhost:3000/v1/erp/procurement/proc_3nLsW8kF9xYtP7/reject \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Exceeds quarterly software budget. Please reduce seat count to 5 and resubmit, or defer to Q2."
  }'

Response

{
  "id": "proc_3nLsW8kF9xYtP7",
  "status": "cancelled",
  "rejected_by": "usr_3kPmN8rT2wXq",
  "rejected_at": 1708733200,
  "reason": "Exceeds quarterly software budget. Please reduce seat count to 5 and resubmit, or defer to Q2."
}

GET/v1/erp/vendors

List vendors

This endpoint returns the list of configured vendors available for procurement requests. Vendors are synced from your ERP system and include contract status, tier classification, and contact information.

Request

GET

/v1/erp/vendors

curl http://localhost:3000/v1/erp/vendors \
  -H "Authorization: Bearer {token}"

Response

{
  "data": [
    {
      "id": "vnd_7xKpQ2mR4wVb",
      "name": "Dell Technologies",
      "status": "active",
      "tier": "strategic",
      "website": "https://www.dell.com",
      "primary_contact_name": "Enterprise Account Manager",
      "primary_contact_email": "enterprise@dell.com",
      "categories": ["hardware", "consumable"],
      "contract_expires_at": 1735689600,
      "tags": ["hardware", "laptops", "servers", "strategic"]
    },
    {
      "id": "vnd_3nLsW8kF9xYt",
      "name": "Hewlett Packard Enterprise",
      "status": "active",
      "tier": "strategic",
      "website": "https://www.hpe.com",
      "primary_contact_name": "Solutions Architect",
      "primary_contact_email": "support@hpe.com",
      "categories": ["hardware", "service"],
      "contract_expires_at": 1735689600,
      "tags": ["hardware", "servers", "storage", "strategic"]
    },
    {
      "id": "vnd_9pRtH5jN2cEm",
      "name": "JetBrains",
      "status": "active",
      "tier": "approved",
      "website": "https://www.jetbrains.com",
      "primary_contact_name": "License Manager",
      "primary_contact_email": "sales@jetbrains.com",
      "categories": ["software_license"],
      "contract_expires_at": 1740960000,
      "tags": ["software", "development-tools", "licensing"]
    },
    {
      "id": "vnd_5pRtH5jN2cEm",
      "name": "Microsoft",
      "status": "active",
      "tier": "strategic",
      "website": "https://www.microsoft.com",
      "primary_contact_name": "Enterprise Account Manager",
      "primary_contact_email": "enterprise@microsoft.com",
      "categories": ["software_license", "service"],
      "contract_expires_at": 1735689600,
      "tags": ["cloud", "software", "licensing", "strategic"]
    }
  ]
}

GET/v1/erp/budgets

Get budget summaries

This endpoint returns budget summaries grouped by cost center. Each summary shows the allocated budget, amount spent, amount committed (in approved but undelivered orders), and remaining balance. This data is synced from your ERP system and updated in real-time as procurement requests are approved and fulfilled.

Optional attributes

Name
cost_center
Type
string
Description
Filter to a specific cost center code (e.g., CC-IT-INFRA).
Name
fiscal_year
Type
integer
Description
Fiscal year to query. Defaults to the current fiscal year.

Request

GET

/v1/erp/budgets

curl -G http://localhost:3000/v1/erp/budgets \
  -H "Authorization: Bearer {token}" \
  -d fiscal_year=2026

Response

{
  "fiscal_year": 2026,
  "data": [
    {
      "cost_center": "CC-IT-OPS",
      "name": "IT Operations",
      "annual_budget": 240000.00,
      "spent": 38420.00,
      "committed": 4200.00,
      "remaining": 197380.00,
      "utilization_percent": 17.76,
      "currency": "USD"
    },
    {
      "cost_center": "CC-IT-DEV",
      "name": "Software Development",
      "annual_budget": 360000.00,
      "spent": 62150.00,
      "committed": 5990.00,
      "remaining": 291860.00,
      "utilization_percent": 18.93,
      "currency": "USD"
    },
    {
      "cost_center": "CC-IT-INFRA",
      "name": "Infrastructure",
      "annual_budget": 480000.00,
      "spent": 124800.00,
      "committed": 12056.00,
      "remaining": 343144.00,
      "utilization_percent": 28.51,
      "currency": "USD"
    },
    {
      "cost_center": "CC-IT-SEC",
      "name": "Information Security",
      "annual_budget": 180000.00,
      "spent": 28500.00,
      "committed": 0.00,
      "remaining": 151500.00,
      "utilization_percent": 15.83,
      "currency": "USD"
    },
    {
      "cost_center": "CC-IT-EUS",
      "name": "End User Support",
      "annual_budget": 120000.00,
      "spent": 19200.00,
      "committed": 1708.00,
      "remaining": 99092.00,
      "utilization_percent": 17.42,
      "currency": "USD"
    }
  ]
}

POST/v1/erp/sync

Trigger ERP sync

This endpoint triggers a manual synchronization with your connected ERP system. The sync pulls updated vendor catalogs, budget allocations, and purchase order statuses. Syncs are processed asynchronously via BullMQ and the response returns a job ID for tracking.

Optional attributes

Name
scope
Type
string
Description
Sync scope. One of full, vendors, budgets, purchase_orders, or catalogs. Defaults to full.
Name
erp_source
Type
string
Description
Limit sync to a specific ERP source: sap_s4hana or oracle_erp. Defaults to all configured sources.

Request

POST

/v1/erp/sync

curl -X POST http://localhost:3000/v1/erp/sync \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "full",
    "erp_source": "sap_s4hana"
  }'

Response

{
  "sync_job_id": "sync_4kPmN8rT2wXq",
  "erp_source": "sap_s4hana",
  "scope": "full",
  "status": "queued",
  "queued_at": 1708733500,
  "estimated_entities": {
    "vendors": 47,
    "budgets": 12,
    "purchase_orders": 186,
    "catalogs": 324
  }
}