---
# === IDENTITY ===
id: business/erp-integration/oracle-scm-cloud-api/2026
canonical_question: "What are the Oracle SCM Cloud API capabilities - inventory, order management, shipping, manufacturing?"
aliases:
  - "Oracle Fusion Supply Chain Management REST API endpoints"
  - "Oracle SCM Cloud inventory and order management API"
  - "Oracle Cloud SCM shipping and manufacturing API integration"
  - "Oracle Fusion Cloud SCM REST API capabilities and FBDI"
entity_type: erp_integration
domain: business > erp-integration > Oracle SCM Cloud API Capabilities
region: global
jurisdiction: global
temporal_scope: 2024-2026

# === SYSTEM PROFILE ===
systems:
  - name: "Oracle Fusion Cloud Supply Chain & Manufacturing (SCM)"
    vendor: "Oracle"
    version: "25D / 26A"
    edition: "All editions"
    deployment: "cloud"
    api_surface: "REST, SOAP, FBDI, BICC"

# === VERIFICATION ===
last_verified: 2026-03-09
confidence: 0.87
version: 1.0
first_published: 2026-03-09

# === TEMPORAL VALIDITY ===
temporal_validity:
  status: volatile
  last_breaking_change: "REST Framework v3 (2022) — expand returns collection resources with pagination"
  next_review: 2026-09-05
  change_sensitivity: high

# === CONSTRAINTS ===
constraints:
  - "Maximum 500 records per REST API response (practical limit 499); use offset+limit for pagination"
  - "REST API supports JSON format only — no XML on REST surface"
  - "FBDI required for bulk operations exceeding 500 records — REST not designed for high-volume ETL"
  - "Business Events must be explicitly enabled per object — not generated by default"
  - "Rate limits tiered by identity domain: Free (150 req/min), Oracle Apps (1,500 req/min), Premium (5,000 req/min)"
  - "Batch REST operations limited to 50 sub-operations per call"
  - "SOAP API deprecated for new SCM development — maintenance-only, use REST for new integrations"

# === SKIP CONDITIONS ===
skip_this_unit_if:
  - condition: "User needs Oracle ERP Cloud Financials REST API (GL, AP, AR, FA)"
    use_instead: "business/erp-integration/oracle-erp-cloud-rest-api-capabilities/2026"
  - condition: "User needs FBDI bulk import details and template reference"
    use_instead: "business/erp-integration/oracle-erp-cloud-fbdi-import/2026"
  - condition: "User needs Oracle Integration Cloud (OIC) adapter and middleware capabilities"
    use_instead: "business/erp-integration/oracle-integration-cloud-capabilities/2026"
  - condition: "User needs Oracle ERP Cloud authentication setup (OAuth, JWT)"
    use_instead: "business/erp-integration/oracle-erp-cloud-authentication/2026"

# === AGENT HINTS ===
inputs_needed:
  - key: integration_pattern
    question: "What integration pattern do you need?"
    type: choice
    options:
      - "real-time sync (individual records, <1s latency)"
      - "batch/bulk (scheduled, high volume)"
      - "event-driven (Business Events via OIC)"
      - "file-based (FBDI CSV import/export)"
  - key: data_volume
    question: "What's your daily data volume?"
    type: choice
    options:
      - "< 1,000 records/day"
      - "1,000-100,000 records/day"
      - "> 100,000 records/day"
  - key: direction
    question: "What's the data flow direction?"
    type: choice
    options:
      - "inbound (writing to Oracle SCM)"
      - "outbound (reading from Oracle SCM)"
      - "bidirectional sync"

# === DISTRIBUTION ===
canonical_source: "https://knowledgelib.io/business/erp-integration/oracle-scm-cloud-api/2026"
suggested_citation: "Source: knowledgelib.io — AI Knowledge Library (verified 2026-03-09)"

# === RELATED UNITS ===
related_kos:
  depends_on:
    - id: "business/erp-integration/oracle-erp-cloud-authentication/2026"
      label: "Oracle ERP Cloud Authentication (OAuth2, JWT) — required before any API call"
  related_to:
    - id: "business/erp-integration/oracle-erp-cloud-rest-api-capabilities/2026"
      label: "Oracle ERP Cloud REST API Capabilities — Financials modules (GL, AP, AR)"
    - id: "business/erp-integration/oracle-erp-cloud-fbdi-import/2026"
      label: "Oracle FBDI Import — bulk data loading for SCM and ERP"
    - id: "business/erp-integration/oracle-integration-cloud-capabilities/2026"
      label: "Oracle Integration Cloud (OIC) — middleware for Business Events and orchestration"
  solves:
    - id: "business/erp-integration/order-to-cash-integration/2026"
      label: "Order-to-Cash integration playbook using SCM Order Management APIs"
  alternative_to:
    - id: "business/erp-integration/oracle-bicc-data-extraction/2026"
      label: "Oracle BICC — alternative for outbound bulk data extraction"
  often_confused_with:
    - id: "business/erp-integration/oracle-erp-cloud-rest-api-capabilities/2026"
      label: "Oracle ERP Cloud REST API — covers Financials, not SCM modules"

# === SOURCES (7 authoritative sources) ===
sources:
  - id: src1
    title: "REST API for Oracle Fusion Cloud SCM — All REST Endpoints (Release 25C)"
    author: Oracle
    url: https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/25c/fasrp/rest-endpoints.html
    type: official_docs
    published: 2025-07-01
    reliability: authoritative
  - id: src2
    title: "Oracle Fusion Cloud SCM Integration Playbooks for SCM 25A"
    author: Oracle
    url: https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/25a/faips/integration-playbooks-for-scm.pdf
    type: official_docs
    published: 2025-02-01
    reliability: authoritative
  - id: src3
    title: "Use REST API with FBDI to Import Large Volumes of Sales Orders"
    author: Oracle
    url: https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/25d/faiom/use-fbdi-and-rest-api-to-import-a-lot-of-sales-orders.html
    type: official_docs
    published: 2025-10-01
    reliability: authoritative
  - id: src4
    title: "Public Business Events Using Oracle Integration Cloud — SCM"
    author: Oracle
    url: https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/24d/faips/scm-public-business-events-using-oracle-integration-cloud.html
    type: official_docs
    published: 2024-10-01
    reliability: authoritative
  - id: src5
    title: "Configure OAuth Using the Fusion Applications Identity Domain"
    author: Oracle
    url: https://docs.oracle.com/en/cloud/saas/applications-common/25b/oaext/configure-oauth.html
    type: official_docs
    published: 2025-04-01
    reliability: authoritative
  - id: src6
    title: "Implement JWT Token Authentication with Fusion Cloud Application (REST/SOAP)"
    author: Oracle A-Team
    url: https://www.ateam-oracle.com/implement-jwt-token-authentication-with-fusion-cloud-application-restsoap-extend-in-nodejs-based-applications
    type: technical_blog
    published: 2024-06-15
    reliability: high
  - id: src7
    title: "Oracle Supply Chain & Manufacturing 26A — REST API Documentation"
    author: Oracle
    url: https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/26a/index.html
    type: official_docs
    published: 2026-02-01
    reliability: authoritative
---

# Oracle SCM Cloud API Capabilities — Inventory, Order Management, Shipping & Manufacturing

## TL;DR

- **Bottom line**: Oracle Fusion Cloud SCM provides REST APIs across five major modules — Inventory Management, Order Management, Manufacturing, Shipping, and Product Data Management — all under the `/fscmRestApi/resources/11.13.18.05/` base path. Use REST for real-time operations under 500 records; use FBDI for bulk imports.
- **Key limit**: 500 records max per REST response (practical limit 499); rate limits tiered at 150/1,500/5,000 requests per minute depending on identity domain type.
- **Watch out for**: REST API is not designed for bulk ETL — attempting to paginate through tens of thousands of records via REST will hit rate limits and perform poorly. Use FBDI + ESS jobs for any volume above 500 records.
- **Best for**: Real-time inventory queries, individual order creation/updates, work order status checks, and event-driven integrations via Business Events through OIC.
- **Authentication**: OAuth 2.0 with Client Credentials or JWT Bearer flow through Fusion Applications Identity Domain (IAM). JWT recommended for server-to-server integrations. [src5]

## System Profile

Oracle Fusion Cloud Supply Chain & Manufacturing (SCM) is a SaaS-only suite covering inventory management, order management, manufacturing execution, shipping/logistics, procurement, and supply chain planning. The REST API follows the common Oracle Fusion REST framework (same pagination, filtering, and authentication patterns as Oracle ERP Cloud Financials) but exposes SCM-specific resources — work orders, transfer orders, shipment lines, on-hand quantities, and sales order orchestration. All editions share the same API surface; rate limits depend on your identity domain tier, not your SCM edition. [src1]

| Property | Value |
|---|---|
| **Vendor** | Oracle |
| **System** | Oracle Fusion Cloud Supply Chain & Manufacturing (SCM) |
| **API Surface** | REST (primary), SOAP (legacy/maintenance), FBDI (bulk), BICC (extraction) |
| **Current API Version** | Release 25D / 26A (resource version 11.13.18.05) |
| **Editions Covered** | All editions — API surface is identical |
| **Deployment** | Cloud (SaaS only) |
| **API Docs URL** | [Oracle Fusion Cloud SCM REST API](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/25c/fasrp/rest-endpoints.html) |
| **Status** | GA (REST); SOAP is maintenance-only for SCM |

## API Surfaces & Capabilities

| API Surface | Protocol | Best For | Max Records/Request | Rate Limit | Real-time? | Bulk? |
|---|---|---|---|---|---|---|
| REST API | HTTPS/JSON | Individual record CRUD, queries <500 records | 500 (pagination via offset) | 150-5,000 req/min (domain tier) | Yes | No |
| SOAP API | HTTPS/XML | Legacy integrations, metadata ops | Varies by service | Shared with REST | Yes | No |
| FBDI (File-Based Data Import) | CSV via UCM + ESS | Bulk import >500 records, data migration | 250 MB per file | ESS job queue (concurrent limits) | No | Yes |
| BICC (BI Cloud Connector) | Incremental extraction | Outbound bulk data extraction to BI/DW | Full table extraction | Scheduled (not real-time) | No | Yes |
| Business Events | Event/callback via OIC | Near-real-time notifications, event-driven | N/A (event payload) | Per-event (no throttle on events) | Yes | N/A |
| Batch REST | HTTPS/JSON | Multi-operation in single call | 50 sub-operations | Counted as 1 request | Yes | Partial |

[src1, src2]

## Rate Limits & Quotas

### Per-Request Limits

| Limit Type | Value | Applies To | Notes |
|---|---|---|---|
| Max records per response | 500 (499 practical) | REST API GET | Use `offset` + `limit` for pagination; default page size is 25 |
| Max payload size | 1 MB | REST API POST/PATCH | Larger payloads rejected with HTTP 413 |
| Max batch sub-operations | 50 | Batch REST API | Each sub-operation is one CRUD action |
| Max FBDI file size | 250 MB | File-Based Data Import | Split larger files into multiple uploads |
| Max query depth | 3 levels | REST API `expand` parameter | Nested child resources limited to 3 levels deep |
| Max fields per request | No hard limit | REST API `fields` parameter | But response time degrades beyond 50 fields |

[src1, src2]

### Rolling / Daily Limits

| Limit Type | Value | Window | Domain Tier Differences |
|---|---|---|---|
| REST API requests | 150-5,000 | Per minute | Free: 150/min, Oracle Apps: 1,500/min, Premium: 5,000/min |
| Concurrent ESS jobs | 4-16 | Per pod | Depends on pod size and configuration |
| FBDI import jobs | No daily cap | Per ESS queue | Limited by concurrent job slots, not daily quota |
| Business Events | No explicit cap | Per event | Volume limited by OIC subscription tier |
| BICC extractions | Scheduled | Per configuration | Typically 1-4 runs per day |

[src1, src5]

## Authentication

| Flow | Use When | Token Lifetime | Refresh? | Notes |
|---|---|---|---|---|
| OAuth 2.0 Client Credentials | Server-to-server, no user context | Configurable (default ~60 min) | Request new token | Recommended for integrations; requires confidential app in IAM |
| OAuth 2.0 JWT Bearer | Server-to-server with user assertion | Configurable (default ~60 min) | New JWT per request | Avoids password expiration issues; requires X.509 certificate |
| Basic Authentication | Quick testing, development only | Session-based | No | Do NOT use in production — exposes credentials, blocked by password rotation policies |
| SAML 2.0 | SSO-based user-context access | Session-based | No | Used with OIC adapter, not direct API calls |

[src5, src6]

### Authentication Gotchas

- JWT bearer flow requires a confidential application in the Fusion IAM identity domain with a digital certificate — self-signed works for dev, CA-signed required for production. [src6]
- OAuth tokens are scoped to the identity domain, not individual users — all API calls execute under the integration user's role and data security policies. [src5]
- Password-based auth is subject to Fusion's password rotation policy (default 90 days) — automated integrations using Basic Auth will break silently when the password expires. Use JWT or Client Credentials instead. [src6]
- When using OIC with Business Events, the OIC adapter handles auth automatically — do not configure separate OAuth for event subscriptions. [src4]

## Constraints
<!-- Agents: read this section before recommending any integration approach from this unit.
     These are hard constraints that must not be violated. -->

- REST API is limited to 500 records per response — any integration requiring more than 500 records per operation must use FBDI or BICC, not REST pagination loops.
- Business Events are not enabled by default — each event type must be explicitly activated in SCM Setup and then subscribed to in OIC. Forgetting to enable events is the #1 cause of "integration doesn't trigger" issues.
- SOAP API is in maintenance mode for SCM modules — Oracle will not add new SOAP services for SCM. All new integrations must use REST.
- FBDI requires UCM (Universal Content Management) for file upload — you cannot POST a CSV directly to an SCM REST endpoint for bulk import. The flow is: upload CSV to UCM via REST, then trigger an ESS import job.
- Rate limits are per identity domain, not per application or user — all integrations sharing a domain share the same rate limit pool.
- Manufacturing work orders support both discrete and process types — the API endpoints differ (`discreteWorkOrders` vs `processWorkOrders`). Using the wrong endpoint silently fails.
- SCM REST API does not support real-time inventory reservation via a single atomic call — reservation requires a two-step process (check availability, then create reservation). Race conditions possible under concurrent access.

## Integration Pattern Decision Tree

```
START — User needs to integrate with Oracle SCM Cloud
├── What's the integration pattern?
│   ├── Real-time (individual records, <1s)
│   │   ├── Data volume < 500 records/operation?
│   │   │   ├── YES → REST API: /fscmRestApi/resources/11.13.18.05/{resource}
│   │   │   └── NO → NOT suitable for REST — use FBDI + ESS job
│   │   └── Need event-driven notifications?
│   │       ├── YES → Business Events via OIC (enable event in SCM Setup first)
│   │       └── NO → REST API polling (acceptable for <1K records, expensive beyond)
│   ├── Batch/Bulk (scheduled, high volume)
│   │   ├── Inbound (writing to SCM)?
│   │   │   ├── < 500 records → REST API (simpler, no FBDI overhead)
│   │   │   ├── 500-250,000 records → FBDI: CSV template → UCM upload → ESS job
│   │   │   └── > 250,000 records → FBDI with file splitting (250 MB per file limit)
│   │   └── Outbound (reading from SCM)?
│   │       ├── < 5,000 records → REST API with pagination
│   │       └── > 5,000 records → BICC incremental extraction
│   ├── Event-driven (near-real-time)
│   │   ├── SCM module supports Business Events?
│   │   │   ├── YES → Subscribe via OIC adapter (guaranteed delivery)
│   │   │   └── NO → REST API polling on LastUpdateDate (not ideal)
│   │   └── Need cross-module orchestration?
│   │       ├── YES → OIC with multiple event subscriptions + process flows
│   │       └── NO → Single OIC integration with callback
│   └── File-based (CSV/XML)
│       └── FBDI → download template, populate CSV, upload to UCM, trigger ESS
├── Which direction?
│   ├── Inbound (writing to SCM) → check rate limits + FBDI thresholds above
│   ├── Outbound (reading from SCM) → REST for real-time, BICC for bulk
│   └── Bidirectional → design conflict resolution FIRST; use LastUpdateDate for change detection
└── Error tolerance?
    ├── Zero-loss required → FBDI (transactional) + OIC error hospital + dead letter queue
    └── Best-effort acceptable → REST API with exponential backoff retry
```

## Quick Reference

| Operation | Method | Endpoint | Module | Notes |
|---|---|---|---|---|
| Get on-hand quantities | GET | `/fscmRestApi/resources/11.13.18.05/inventoryOnhandBalanceSummaries` | Inventory | Summary-level; use child resources for serial/lot details |
| Create transfer order | POST | `/fscmRestApi/resources/11.13.18.05/transferOrders` | Inventory | Supports child `transferOrderLines` for line items |
| Get inventory movement requests | GET | `/fscmRestApi/resources/11.13.18.05/inventoryMovementRequests` | Inventory | Types: Requisition, Replenishment, Pick Wave, Shop Floor |
| Create pick slip | POST | `/fscmRestApi/resources/11.13.18.05/inventoryMovementRequests/{id}/action/createPickSlip` | Inventory | Custom action on movement request |
| Get shipment lines | GET | `/fscmRestApi/resources/11.13.18.05/shipmentLines` | Shipping | Inbound and outbound shipment tracking |
| Get inbound shipments | GET | `/fscmRestApi/resources/11.13.18.05/inboundShipments` | Receiving | Includes child resources: shipmentLines, attachments |
| Create supply request | POST | `/fscmRestApi/resources/11.13.18.05/supplyRequests` | Supply Chain Orchestration | Supports transfer and purchase supply-order types |
| Get sales orders (Order Hub) | GET | `/fscmRestApi/resources/11.13.18.05/salesOrdersForOrderHubRequests` | Order Mgmt | Paginated; child resources for lines, holds, fulfillment |
| Create sales order action | POST | `/fscmRestApi/resources/11.13.18.05/salesOrderActionRequests` | Order Mgmt | Supports submit, cancel, hold actions |
| Get discrete work orders | GET | `/fscmRestApi/resources/11.13.18.05/discreteWorkOrders` | Manufacturing | Child resources: operations, materials, resources, serials |
| Get process work orders | GET | `/fscmRestApi/resources/11.13.18.05/processWorkOrders` | Manufacturing | Process manufacturing; different from discrete |
| Create material transaction | POST | `/fscmRestApi/resources/11.13.18.05/materialTransactions` | Manufacturing | Shop floor to/from subinventory movement |
| Get work order dispatch list | GET | `/fscmRestApi/resources/11.13.18.05/dispatchListWorkOrderOperations` | Manufacturing | Operator dispatch queue |
| Get shipping methods | GET | `/fscmRestApi/resources/11.13.18.05/carriers/{id}/child/shippingMethods` | SCM Common | Carrier service levels and transport methods |
| Get available supply sources | GET | `/fscmRestApi/resources/11.13.18.05/availableSupplySources` | Orchestration | Supply sources for transfer order fulfillment |

[src1, src2, src7]

## Step-by-Step Integration Guide

### 1. Authenticate and obtain access token

Obtain an OAuth 2.0 access token from the Fusion Applications Identity Domain using Client Credentials flow. You need a confidential application configured in the IAM domain with appropriate SCM role grants. [src5]

```bash
# Request OAuth 2.0 access token using Client Credentials
curl -X POST "https://{identity-domain}.identity.oraclecloud.com/oauth2/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "{client_id}:{client_secret}" \
  -d "grant_type=client_credentials&scope=urn:opc:resource:consumer::all"
```

**Verify**: Response contains `access_token` field with a JWT string and `expires_in` value.

### 2. Query on-hand inventory balances

Use the inventoryOnhandBalanceSummaries resource to check current stock levels for a specific item and organization. [src1]

```bash
# Get on-hand quantities for a specific item in an organization
curl -X GET "https://{host}/fscmRestApi/resources/11.13.18.05/inventoryOnhandBalanceSummaries?q=ItemNumber='AS54888';OrganizationCode='M1'&limit=500" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"
```

**Verify**: Response JSON contains `items` array with `OnhandQuantity`, `ReservedQuantity`, and `AvailableQuantity` fields.

### 3. Create a sales order via Order Hub

Submit a new sales order through the Order Management module. The sales order creation uses an action request pattern — you post a request that triggers asynchronous order processing. [src3]

```bash
# Create a sales order action request
curl -X POST "https://{host}/fscmRestApi/resources/11.13.18.05/salesOrdersForOrderHub" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "SourceTransactionNumber": "EXT-SO-001",
    "SourceTransactionSystem": "EXTERNAL_SYSTEM",
    "OrderedDate": "2026-03-09T00:00:00+00:00",
    "BuyingPartyName": "Acme Corp",
    "lines": [{
      "SourceTransactionLineNumber": "1",
      "ProductNumber": "AS54888",
      "OrderedQuantity": 10,
      "OrderedUOM": "Ea"
    }]
  }'
```

**Verify**: Response returns `HeaderId` and processing status. Poll `salesOrderActionRequests/{id}` for completion status.

### 4. Paginate through large result sets

Oracle SCM REST API returns max 500 records per call. Use `offset` and `limit` parameters to paginate. The `hasMore` flag in the response indicates whether additional pages exist. [src1]

```bash
# First page
curl -X GET "https://{host}/fscmRestApi/resources/11.13.18.05/shipmentLines?limit=500&offset=0" \
  -H "Authorization: Bearer {access_token}"

# Subsequent pages — increment offset by limit value
curl -X GET "https://{host}/fscmRestApi/resources/11.13.18.05/shipmentLines?limit=500&offset=500" \
  -H "Authorization: Bearer {access_token}"
```

**Verify**: Check `hasMore` field in response. When `hasMore: false`, all records have been retrieved.

### 5. Bulk import via FBDI (for >500 records)

For bulk operations, upload a CSV file to UCM and trigger an ESS import job. This is the recommended pattern for data migration and scheduled batch loads. [src3]

```bash
# Step 1: Upload CSV to UCM (Universal Content Management)
curl -X POST "https://{host}/fscmRestApi/resources/11.13.18.05/erpintegrations" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "OperationName": "importBulkData",
    "DocumentContent": "BASE64_ENCODED_ZIP_FILE",
    "ContentType": "zip",
    "FileName": "SalesOrderImport.zip",
    "DocumentAccount": "scm$/salesOrderImport$"
  }'

# Step 2: Trigger ESS import job
curl -X POST "https://{host}/fscmRestApi/resources/11.13.18.05/erpintegrations" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "OperationName": "submitESSJobRequest",
    "JobPackageName": "/oracle/apps/ess/scm/doo/decomposition/receiveSalesOrder",
    "JobDefName": "ImportOrdersJob",
    "ESSParameters": "EXTERNAL_SYSTEM,N,Y"
  }'
```

**Verify**: Response returns `ReqstId` (ESS job ID). Poll job status via `GET /fscmRestApi/resources/11.13.18.05/erpintegrations?finder=ESSJobStatusRF;requestId={ReqstId}` until status is `SUCCEEDED`.

### 6. Subscribe to Business Events via OIC

For event-driven integration, subscribe to SCM Business Events through Oracle Integration Cloud. Events must be enabled in SCM Setup before they can be consumed. [src4]

```
OIC Integration Flow:
1. Create OIC integration with Oracle ERP Cloud Adapter as trigger
2. Select "Subscribe to Business Events" connection type
3. Choose SCM event: e.g., "Sales Order Event" (oracle.apps.scm.doo.event.SalesOrderEvent)
4. Map event payload to target system
5. Activate integration

Available SCM Business Events include:
- Sales Order lifecycle events (create, update, fulfill, ship, close)
- Inventory transaction events (receipt, issue, transfer)
- Purchase Order events (approval, receipt)
- Work Order events (release, complete)
- Shipment events (ship confirm, delivery)
```

**Verify**: In OIC Monitoring > Integrations, confirm the integration shows "Active" and events are being received after triggering a test transaction in SCM.

## Code Examples

### Python: Query Inventory On-Hand Balances

```python
# Input:  OAuth2 credentials (client_id, client_secret), item number, org code
# Output: On-hand quantity details for the specified item

import requests
from requests.auth import HTTPBasicAuth

# Configuration
FUSION_HOST = "https://your-instance.fa.us2.oraclecloud.com"
IAM_HOST = "https://your-domain.identity.oraclecloud.com"
CLIENT_ID = "your_client_id"
CLIENT_SECRET = "your_client_secret"

# Step 1: Get OAuth token
token_resp = requests.post(
    f"{IAM_HOST}/oauth2/v1/token",
    auth=HTTPBasicAuth(CLIENT_ID, CLIENT_SECRET),
    data={"grant_type": "client_credentials", "scope": "urn:opc:resource:consumer::all"}
)
token_resp.raise_for_status()
access_token = token_resp.json()["access_token"]

# Step 2: Query on-hand balances
headers = {"Authorization": f"Bearer {access_token}", "Content-Type": "application/json"}
params = {
    "q": "ItemNumber='AS54888';OrganizationCode='M1'",
    "limit": 500,
    "fields": "ItemNumber,OrganizationCode,OnhandQuantity,ReservedQuantity,AvailableQuantity"
}
resp = requests.get(
    f"{FUSION_HOST}/fscmRestApi/resources/11.13.18.05/inventoryOnhandBalanceSummaries",
    headers=headers, params=params
)
resp.raise_for_status()
for item in resp.json().get("items", []):
    print(f"Item: {item['ItemNumber']}, On-Hand: {item['OnhandQuantity']}, Available: {item['AvailableQuantity']}")
```

### JavaScript/Node.js: Create Transfer Order

```javascript
// Input:  OAuth2 credentials, source/destination org, item details
// Output: Transfer order ID and status

const axios = require('axios'); // v1.6+

const FUSION_HOST = 'https://your-instance.fa.us2.oraclecloud.com';
const IAM_HOST = 'https://your-domain.identity.oraclecloud.com';

async function createTransferOrder(token, sourceOrg, destOrg, itemNumber, qty) {
  const resp = await axios.post(
    `${FUSION_HOST}/fscmRestApi/resources/11.13.18.05/transferOrders`,
    {
      SourceOrganizationCode: sourceOrg,
      DestinationOrganizationCode: destOrg,
      transferOrderLines: [{
        ItemNumber: itemNumber,
        Quantity: qty,
        UOM: 'Ea'
      }]
    },
    { headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' } }
  );
  return resp.data; // Contains HeaderId, OrderNumber, Status
}

// Usage with retry on rate limit (429)
async function withRetry(fn, maxRetries = 5) {
  for (let i = 0; i < maxRetries; i++) {
    try { return await fn(); } catch (err) {
      if (err.response?.status === 429 && i < maxRetries - 1) {
        const wait = Math.pow(2, i) * 1000; // Exponential backoff
        console.log(`Rate limited, retrying in ${wait}ms...`);
        await new Promise(r => setTimeout(r, wait));
      } else throw err;
    }
  }
}
```

### cURL: Check Work Order Status

```bash
# Input:  Access token, work order number or ID
# Output: Work order status, operation details, material requirements

# Get discrete work order details with operations and materials
curl -X GET "https://{host}/fscmRestApi/resources/11.13.18.05/discreteWorkOrders?q=WorkOrderNumber='WO-001'&expand=operations,operations.materials&fields=WorkOrderNumber,WorkOrderStatusCode,PlannedStartDate,PlannedCompletionDate" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"

# Expected response shape:
# {
#   "items": [{
#     "WorkOrderNumber": "WO-001",
#     "WorkOrderStatusCode": "Released",
#     "PlannedStartDate": "2026-03-10T08:00:00+00:00",
#     "PlannedCompletionDate": "2026-03-12T17:00:00+00:00",
#     "operations": { "items": [...] }
#   }],
#   "hasMore": false
# }
```

## Data Mapping

### Field Mapping Reference

| Source Field (External) | Target Field (Oracle SCM) | Type | Transform | Gotcha |
|---|---|---|---|---|
| External Order ID | SourceTransactionNumber | String(50) | Direct | Must be unique per SourceTransactionSystem |
| Item SKU | ProductNumber / ItemNumber | String(300) | Direct | Must match Oracle Item Master; case-sensitive |
| Quantity | OrderedQuantity / Quantity | Number | Direct | Decimal precision varies by UOM — use 2 decimal places for "Ea" |
| Unit of Measure | OrderedUOM / UOM | String(3) | Map to Oracle UOM code | Must use Oracle UOM codes (Ea, Kg, Lb), not source system codes |
| Ship-to Address | ShipToAddress fields | Multiple | Map to party site | Oracle uses party model — need PartyId or PartySiteId, not raw address |
| Date/Time | *Date fields | ISO 8601 | Ensure UTC or include offset | Oracle stores in UTC internally; display timezone from user preference |
| Currency | CurrencyCode | String(3) | ISO 4217 code | Multi-currency must be enabled at org level; conversion rates must exist |
| Status | StatusCode | String enum | Map to Oracle status codes | Status values are module-specific: "Released", "Booked", "Closed" etc. |

### Data Type Gotchas

- Oracle SCM datetime fields are stored in UTC internally but displayed per user timezone preference — always pass dates with explicit timezone offset (ISO 8601 format) to avoid off-by-one-day errors. [src1]
- Oracle uses a party-site data model for addresses — you cannot pass raw address strings to Order Management. You must first create or look up the Party and PartySite, then reference by ID. [src2]
- Item numbers in Oracle are case-sensitive in REST API queries — `q=ItemNumber='as54888'` will return no results if the item is stored as `AS54888`. [src1]
- Oracle SCM uses UOM codes that may differ from external systems — "Each" is `Ea`, "Kilogram" is `Kg`. The UOM must exist in Oracle's UOM class definition or the API call fails silently with a validation error. [src2]

## Error Handling & Failure Points

### Common Error Codes

| Code | Meaning | Cause | Resolution |
|---|---|---|---|
| 400 | Bad Request | Invalid payload, missing required field, wrong data type | Check request body against API docs; validate field names are exact match |
| 401 | Unauthorized | Expired or invalid OAuth token | Refresh token; check token scope includes SCM resources |
| 403 | Forbidden | Insufficient role/data security | Grant integration user appropriate SCM duty roles (e.g., SCM Integration Specialist) |
| 404 | Not Found | Invalid endpoint path or resource version mismatch | Verify resource version (11.13.18.05) and resource name spelling |
| 429 | Too Many Requests | Rate limit exceeded for identity domain | Implement exponential backoff; check domain tier (Free=150/min) |
| 500 | Internal Server Error | Server-side processing failure, often data validation | Check ESS job logs; may indicate invalid business rule violation |
| 503 | Service Unavailable | Maintenance window or pod restart | Retry after 5 minutes; check Oracle Cloud status page |

[src1, src2]

### Failure Points in Production

- **FBDI import succeeds but records not visible**: ESS job completes with "Succeeded" status but import had validation errors. Fix: `Always check the ESS job output file (not just status) — download output via UCM and inspect error rows`. [src3]
- **Business Events stop firing after SCM update**: Oracle quarterly updates can reset event enablement flags. Fix: `After each quarterly update (A/B/C/D), verify Business Event enablement in SCM Setup > Business Events page`. [src4]
- **REST API returns stale inventory data**: On-hand query returns cached data during high-transaction periods. Fix: `Use the inventoryOnhandBalanceSummaries resource (not the legacy endpoint) and add a unique query parameter to bypass caching`. [src1]
- **Transfer order creation fails silently**: POST returns 200 but order is not created. Fix: `Check the response body for embedded error messages in the 'informationalMessage' field — Oracle REST often returns 200 with inline errors instead of 400`. [src2]
- **OAuth token works for Financials but not SCM**: Token scope doesn't include SCM resources. Fix: `In IAM confidential app configuration, ensure the scope includes SCM-specific resource types, not just ERP`. [src5]
- **Pagination loop runs forever**: `hasMore` flag stays true due to new records being inserted during pagination. Fix: `Add a date filter (e.g., LastUpdateDate < pagination_start_time) to freeze the result set during pagination`. [src1]

## Anti-Patterns

### Wrong: Polling REST API every minute for inventory changes

```python
# BAD — consumes rate limit budget, returns entire dataset each time
while True:
    resp = requests.get(f"{host}/fscmRestApi/resources/11.13.18.05/inventoryOnhandBalanceSummaries?limit=500")
    process_all_records(resp.json()["items"])
    time.sleep(60)
```

### Correct: Use Business Events for change notifications, REST for targeted queries

```python
# GOOD — event-driven: OIC receives inventory transaction event, calls your webhook
# Your webhook endpoint receives only changed records
@app.route('/webhook/inventory-change', methods=['POST'])
def handle_inventory_event(event_payload):
    item_id = event_payload['ItemId']
    org_id = event_payload['OrganizationId']
    # Fetch current state for just the changed item
    resp = requests.get(
        f"{host}/fscmRestApi/resources/11.13.18.05/inventoryOnhandBalanceSummaries"
        f"?q=ItemId={item_id};OrganizationId={org_id}",
        headers=auth_headers
    )
    update_local_cache(resp.json()["items"][0])
```

### Wrong: Using REST API for bulk data migration

```python
# BAD — paginating through 50K records via REST; hits rate limits, takes hours
for offset in range(0, 50000, 500):
    resp = requests.get(f"{host}/fscmRestApi/.../items?limit=500&offset={offset}")
    insert_to_target(resp.json()["items"])
```

### Correct: Use FBDI for bulk loads, REST only for real-time operations

```python
# GOOD — FBDI for bulk: upload CSV to UCM, trigger ESS job
import base64, zipfile, io

# 1. Create FBDI CSV from source data
csv_data = generate_fbdi_csv(source_records)  # Use Oracle FBDI template format
zip_buffer = io.BytesIO()
with zipfile.ZipFile(zip_buffer, 'w') as zf:
    zf.writestr('ItemImport.csv', csv_data)

# 2. Upload to UCM and trigger import
encoded = base64.b64encode(zip_buffer.getvalue()).decode()
requests.post(f"{host}/fscmRestApi/resources/11.13.18.05/erpintegrations", json={
    "OperationName": "importBulkData",
    "DocumentContent": encoded,
    "ContentType": "zip",
    "FileName": "ItemImport.zip"
}, headers=auth_headers)
```

### Wrong: Ignoring inline error messages in 200 responses

```python
# BAD — assumes 200 status means success
resp = requests.post(f"{host}/fscmRestApi/.../transferOrders", json=payload)
if resp.status_code == 200:
    print("Success!")  # May actually have validation errors in response body
```

### Correct: Check response body for embedded error/warning messages

```python
# GOOD — inspect informationalMessage and nested error fields
resp = requests.post(f"{host}/fscmRestApi/.../transferOrders", json=payload, headers=auth_headers)
data = resp.json()
if resp.status_code == 200:
    errors = data.get("informationalMessage", [])
    if any(msg.get("severity") == "ERROR" for msg in errors):
        raise ValueError(f"Oracle returned 200 with errors: {errors}")
    print(f"Transfer order created: {data.get('OrderNumber')}")
```

## Common Pitfalls

- **Using the wrong work order endpoint**: Discrete manufacturing uses `discreteWorkOrders`; process manufacturing uses `processWorkOrders`. The endpoints have different field structures. Calling the wrong one returns 404 or empty results. Fix: `Check the organization's manufacturing type in SCM Setup before choosing the endpoint`. [src1]
- **Not enabling Business Events before subscribing**: Events must be enabled in SCM Setup > Business Events for each specific event type. Creating an OIC subscription alone is insufficient. Fix: `Enable events at Setup > SCM > Business Events page, then create the OIC subscription`. [src4]
- **Hardcoding resource version 11.13.18.05**: While this version has been stable, Oracle can deprecate resource versions with quarterly updates. Fix: `Use the Describe endpoint (GET /fscmRestApi/resources/) to discover current resource versions programmatically`. [src1]
- **Not handling UCM file naming conflicts**: FBDI uploads to UCM with the same filename overwrite previous files without warning. Fix: `Append timestamp or UUID to FBDI filenames: ItemImport_20260309_143022.zip`. [src3]
- **Assuming SCM API availability equals ERP API availability**: SCM modules can be on different maintenance windows than Financials. Fix: `Check Oracle Cloud status page for SCM-specific maintenance windows, not just ERP`. [src2]
- **Ignoring ESS job concurrency limits**: Submitting too many FBDI jobs simultaneously blocks the ESS queue for all users. Fix: `Queue FBDI jobs with 30-second delays between submissions; monitor ESS job slots before submitting`. [src3]

## Diagnostic Commands

```bash
# Test authentication — get token and verify
curl -s -X POST "https://{iam-host}/oauth2/v1/token" \
  -u "{client_id}:{client_secret}" \
  -d "grant_type=client_credentials&scope=urn:opc:resource:consumer::all" | jq .access_token

# Check API availability — describe available resources
curl -s -X GET "https://{host}/fscmRestApi/resources/" \
  -H "Authorization: Bearer {token}" | jq '.items[] | .name'

# Verify SCM resource accessibility — list inventory orgs
curl -s -X GET "https://{host}/fscmRestApi/resources/11.13.18.05/inventoryOrganizations?limit=5" \
  -H "Authorization: Bearer {token}" | jq '.items[] | {name: .OrganizationCode}'

# Check on-hand quantity for specific item
curl -s -X GET "https://{host}/fscmRestApi/resources/11.13.18.05/inventoryOnhandBalanceSummaries?q=ItemNumber='AS54888'&limit=5" \
  -H "Authorization: Bearer {token}" | jq '.items[0] | {item: .ItemNumber, onhand: .OnhandQuantity}'

# Monitor ESS job status (for FBDI imports)
curl -s -X GET "https://{host}/fscmRestApi/resources/11.13.18.05/erpintegrations?finder=ESSJobStatusRF;requestId={job_id}" \
  -H "Authorization: Bearer {token}" | jq '.items[0] | {status: .RequestStatus}'

# List available Business Events for subscription
curl -s -X GET "https://{host}/fscmRestApi/resources/11.13.18.05/publicBusinessEvents?limit=100" \
  -H "Authorization: Bearer {token}" | jq '.items[] | .EventName'
```

## Version History & Compatibility

| API Version | Release Date | Status | Breaking Changes | Migration Notes |
|---|---|---|---|---|
| 26A | 2026-02 | Current | New inventory RFID events resource | No breaking changes from 25D |
| 25D | 2025-10 | Supported | Enhanced FBDI+REST combined import for sales orders | New endpoint for combined FBDI/REST order import |
| 25C | 2025-07 | Supported | None | Documentation refresh; new process work order actions |
| 25B | 2025-04 | Supported | Ship confirm rules resource added | New shipping management endpoints |
| 25A | 2025-02 | Supported | Supply request PATCH now requires SupplyOrderReferenceNumber | Must include reference number for supply order updates |
| 24D | 2024-10 | Supported | Business Events documentation expanded for SCM | Additional event types available |
| 24C | 2024-07 | Minimum supported | None | Minimum version for work order material transactions |

[src1, src2, src7]

### Deprecation Policy

Oracle follows a quarterly release cadence (A/B/C/D per year) with REST API resource versions that remain stable across releases. SOAP APIs for SCM are in maintenance-only mode with no new services planned. Oracle typically provides 2-4 quarters notice before deprecating REST resource versions, but the base resource version (11.13.18.05) has been stable since REST Framework v3. Always verify against current release notes before and after quarterly updates. [src2]

## When to Use / When Not to Use

| Use When | Don't Use When | Use Instead |
|---|---|---|
| Real-time inventory queries for <500 items | Bulk inventory data extraction for BI/analytics | BICC (business/erp-integration/oracle-bicc-data-extraction/2026) |
| Individual sales order creation/updates | Mass order import (>500 orders) | FBDI + ESS job (business/erp-integration/oracle-erp-cloud-fbdi-import/2026) |
| Work order status checks and updates | Full manufacturing execution system integration | OIC + Business Events (business/erp-integration/oracle-integration-cloud-capabilities/2026) |
| Shipment tracking and status queries | Warehouse management system integration (WMS) | Oracle WMS Cloud direct integration |
| Event-driven notifications via Business Events | Real-time streaming data (sub-second latency) | Oracle Golden Gate or direct DB replication (not supported on SaaS) |
| Quick lookup of item, org, or UOM master data | Full master data synchronization | BICC incremental extraction + data lake |

## Important Caveats

- Rate limits are per identity domain, not per integration — if multiple integrations share an identity domain, they compete for the same rate limit pool. Monitor aggregate usage across all integrations.
- Business Events have at-least-once delivery semantics — your integration must be idempotent to handle duplicate events, which occur during OIC restarts or network retries.
- FBDI template formats change with Oracle quarterly updates — always download the latest FBDI template from Oracle after each update rather than reusing templates from previous releases.
- Test environments (Oracle Cloud test instances) have lower ESS concurrency limits than production — integration performance testing on test instances underestimates production throughput.
- Oracle SCM REST API documentation lags behind actual API capabilities by 1-2 quarters — new resources may be available before they appear in docs. Use the Describe endpoint to discover available resources.
- Rate limit information is not published in official docs for Fusion Cloud SaaS — the 150/1,500/5,000 per minute tiers are from Oracle support notes and community sources. Oracle can change these without notice.

## Related Units

- [Oracle ERP Cloud REST API Capabilities](/business/erp-integration/oracle-erp-cloud-rest-api-capabilities/2026)
- [Oracle ERP Cloud Authentication (OAuth2, JWT)](/business/erp-integration/oracle-erp-cloud-authentication/2026)
- [Oracle FBDI Import](/business/erp-integration/oracle-erp-cloud-fbdi-import/2026)
- [Oracle Integration Cloud (OIC) Capabilities](/business/erp-integration/oracle-integration-cloud-capabilities/2026)
- [Oracle BICC Data Extraction](/business/erp-integration/oracle-bicc-data-extraction/2026)
- [Order-to-Cash Integration Playbook](/business/erp-integration/order-to-cash-integration/2026)