POST API – Business Object Creation

What is the POST API?

The POST API is used to create business objects in SupplyOn. In this sense, the POST method acts as a Push — some SupplyOn API specifications therefore label it "Push" instead of "POST". See Chapter 4 for the full business object / direction overview.

POST APIs are processed asynchronously.

This means:

  • The API response only confirms receipt of the transmission at the SupplyOn API Gateway / middleware, not successful business processing
  • Business validation and processing happen asynchronously in backend systems
  • The final processing result is not included in the synchronous response

To obtain the final processing result, a combination of synchronous and asynchronous responses is used.

Synchronous Response (Technical Acknowledgement)

The synchronous response provides an immediate confirmation that the request was successfully received and forwarded to SupplyOn internal message handling.

It does not confirm successful business processing.

Response attributes:

  • TransactionID
    Unique identifier of the message handling process
    → Used to correlate with the asynchronous response
  • StatusCode
    High-level transmission status (e.g. OK, ERROR)
  • StatusText
    Additional information, including the SupplyOn Track-ID (SCMA ID)
    → Required for support and message tracking

Example:

{
 "TransactionID": "488AC8AF0ADD71AA26A401547B2CFBEB",
 "StatusCode": "OK",
 "StatusText": "Call received with SupplyOn Track-ID:SCMA0000012345"
}

Asynchronous Response (Status Notification)

The asynchronous response provides the final result of message processing within SupplyOn.

It contains detailed validation and processing results after the message has been:

  • validated
  • routed
  • processed
  • persisted in the SCC system (where applicable)

Correlation

  • The field uuid corresponds to the TransactionID from the synchronous response
  • This enables end-to-end tracking of the message lifecycle

Processing Results

Success

The message was successfully processed and stored.

{
 "uuid": "488AC8AF8E1C12B293C343BF54608581",
 "status": "OK"
}

Error Handling

If processing fails, detailed error information is returned.

Errors are categorized into three types:

1. Syntax Errors (Prefix: S)
Issues with message structure or format.

Typical causes:

  • Missing mandatory fields
  • Invalid data types
  • Length violations
{
 "uuid": "488AC8AF8E1C12B293C343BF54608582",
 "status": "ERROR",
 "Errors": [
 {
 "Code": "S002",
 "Text": "Invalid message structure! A mandatory field is missing..."
 }
 ]
}

2. Routing Errors (Prefix: R)
Issues with partner setup or routing configuration.

Typical causes:

  • Invalid Routing Triple
  • Missing master data
  • Supplier not onboarded
{
 "uuid": "488AC8AF8AE134B15895B0EE40016820",
 "status": "ERROR",
 "Errors": [
 {
 "Code": "R003",
 "Text": "No customer control point found..."
 }
 ]
}

3. Booking Errors (Prefix: B)
Violations of business rules in the SCM system.

Typical causes:

  • Logical inconsistencies (e.g. invalid dates)
  • Configuration issues
{
 "uuid": "488AC8AF8AE134B15895B0EE40016821",
 "status": "ERROR",
 "Errors": [
 {
 "Code": "B001",
 "Text": "Unregistered supplier service not enabled..."
 }
 ]
}

Important Note

The API consumer must provide a StatusNotification endpoint to receive asynchronous responses.

If no endpoint is available, alternative mechanisms (e.g. email-based notification) must be agreed individually.

StatusNotification – Payload Sent by SupplyOn

In this interaction, SupplyOn is the API consumer, not the provider: SupplyOn calls the StatusNotification endpoint that the customer / partner implements and exposes to receive asynchronous processing results. The partner is responsible for hosting this endpoint (with its own server URL) and for accepting the payload described below.

The authoritative payload specification — the same file shared with partners — is attached here: StatusNotification.json.

Open point: The authentication method for calls to the partner's StatusNotification endpoint still needs to be clarified with SupplyOn and will be documented here once defined.

Who Uses the POST API?

The POST API is typically used by different parties depending on the business object and its ownership within the business process.

The following role distribution reflects the standard usage pattern, but may vary depending on specific integration scenarios.

Buy-side Customer → SupplyOn

Used for creating business objects such as:

  • Orders
  • Delivery Schedules
  • Kanban
  • Goods Receipt

Buy-side and Sell-side Customer → SupplyOn

  • Stock Movements

Sell-side Customer (Supplier) → SupplyOn

Used for creating:

  • Demand Responses
  • Advanced Shipping Notification / Forwarder Pickup Advices

This role model is based on the typical ownership of business data within supply chain processes.

However, depending on individual integration setups, alternative usage patterns are possible (e.g. buy-side retrieval or creation in specific scenarios).

Example: Purchase Order (POST)

From a Buy-side Customer perspective, the POST API allows creating a Purchase Order directly in SupplyOn.

The API payload is sent as JSON and follows a structured and reusable schema that is consistently used across different SCC business objects.

Conceptual Structure of a Purchase Order

A Purchase Order consists of generic, reusable sections and order-specific sections:

  • GenericHeaderData
    Contains general message and routing information that is mandatory for all business objects.
    It includes sender and receiver identifiers, message timestamp, and the Routing Triple, which is used by SupplyOn to correctly route and assign the message.
  • GenericInboundData
    Contains identifiers for technical and business-level tracking, such as message number, document number, and ERP system reference.
    This data ensures traceability and correlation across systems.
  • PurchaseOrderHeader
    Contains header-level information for the order, such as order number, order date, currency, and overall order attributes.
    This section exists once per Purchase Order.
  • Address
    Represents one or more business partner addresses (e.g. buyer, supplier, ship-to).
    Address structures are reused across multiple business object types.
  • PurchaseOrderPosition
    Represents the line items of the Purchase Order
    A Purchase Order typically consists of one header and one or more positions, where each position contains item-specific data such as material, quantity, and basic delivery information. 
  • Schedule Lines
    Represents the detailed delivery schedule for each Purchase Order position.
    Each position can contain one or more schedule lines, which define:

    - specific delivery dates
    - corresponding quantities

    This allows a single position to be delivered in multiple partial shipments over time.

Note:
Sections marked as Generic (e.g. GenericHeaderData, GenericInboundData) are shared across all POST APIs, while object-specific sections (such as order header and positions) vary depending on the business object.

The Routing Triple

The Routing Triple identifies the business relationship between a Buy-side and Sell-side Customer and is part of every POST payload (via GenericHeaderData) — not just the Order Response. It always consists of the following three elements:

  • orgCode – Buying organization
  • plantCode – Plant or location
  • supplierNumber – Supplier identifier

These three values must match the values used in the related business object (e.g. the original Purchase Order) to allow SupplyOn to correctly associate a message with the relevant trading partners.

All fields defined in the schema represent either:

  • Mandatory data required for successful processing, or
  • Optional business information supported by SupplyOn.

The complete and authoritative field-level definition, including mandatory indicators and data types, is provided in the OpenAPI specification YAML, which serves as the technical contract for API consumers.

These specifications can be found on the SupplyOn API Developer Portal (PRD / QAS).

Was this article helpful?