Spendint API - POST /sn_spend_intg/spendint/orderack

  • Release version: Yokohama
  • Updated January 30, 2025
  • 4 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Spendint API - POST /snspendintg/spendint/orderack

    The Spendint API’sPOST /snspendintg/spendint/orderackendpoint allows ServiceNow customers to update order information related to purchases made from third-party catalogs. It supports sending order acknowledgments back to ServiceNow after users check out, enabling the purchase lines to be processed for approvals and tasks. This integration is essential for synchronizing order status between ServiceNow, third-party suppliers, and Enterprise Resource Planning (ERP) systems.

    Show full answer Show less

    Key Features

    • Order Synchronization: Updates purchase order headers and lines in ServiceNow’s Outbound Order and Outbound Order Line tables.
    • Supplier Integration: Suppliers can query pending orders via scoped apps and Workflow Studio actions, filtering by supplier ID and purchase order status.
    • Order Lifecycle Management: Purchase orders remain in Pending Submission until confirmations are received from both third-party catalogs and ERP (if applicable), after which their state updates to Ordered.
    • REST API Parameters: Supports asynchronous (default) and synchronous modes to handle third-party integration workflows.
    • Request Payload: Requires customer ID, supplier ID, purchase order number, status code (confirmed or rejected), optional status message, and detailed sales order line information including estimated arrival dates.
    • Error Handling: Provides an Order Acknowledgment Error table to query failed acknowledgments and detailed error messages for troubleshooting.
    • Response Format: JSON response indicating success or failure, with detailed error messages on failure when using synchronous mode.

    Practical Use for ServiceNow Customers

    By integrating with this API, customers can:

    • Ensure order statuses from third-party catalogs are accurately reflected in their ServiceNow system.
    • Automate the transition of purchase orders through approval workflows and ERP synchronization.
    • Monitor and troubleshoot order acknowledgment failures using error tables and detailed API responses.
    • Leverage asynchronous or synchronous modes to tailor integration performance and reliability.

    Expected Outcomes

    • Improved order processing accuracy and visibility across procurement workflows.
    • Seamless integration between ServiceNow, suppliers, and ERP systems, reducing manual reconciliation.
    • Robust error tracking enabling rapid resolution of order submission issues.
    • Consistent and timely updates of purchase order statuses ensuring operational efficiency.

    Updates order information for when a user shops for a product from a third-party catalog. When the user checks out, a purchase line is created so that approvals or other tasks for the purchase can be completed.

    When a purchase order is generated in the ServiceNow database, the order is pushed into the following tables:
    • Outbound Order: Contains the order header.
    • Outbound Order Line: Contains the order lines.

    Suppliers need to query these tables and fetch the orders that are pending against them. Suppliers should create a scoped app for Workflow Studio actions for integrating with the ServiceNow database.

    Query the tables with the following parameters:
    • sysparm_query=supplier_id=<supplier_id>^purchase_order.status=20 for header
    • sysparm_query=purchase_order.supplier_id=<supplier_id>^purchase_order.status=20 for header
    When a purchase line is converted to a purchase order line, the following processes are run:
    1. The purchase order and purchase order line are submitted to the Enterprise Resource Planning (ERP), if applicable.
    2. The purchase order and purchase order line are transferred through integration to the third party with the customer ID, supplier ID, purchase order number, order date, purchase order amount, purchase order amount currency, and purchase order lines.
    3. The purchase order and purchase order line remain in the Pending Submission state until confirmation messages are received by both the third-party catalog integration and the ERP. After confirmation is received, the state is updated to Ordered. If there is no ERP integration involved, a confirmation message is required only from the third-party integration.

    Status tables

    To know the status of the order acknowledgment request, make a REST call into the ServiceNow database using the Table REST API. The response from the API lists the records where the order acknowledgment request failed. For an order acknowledgment response, query the Order Acknowledgment Error table with the following parameter:

    sysparm_query=outbound_error.supplier_id=<supplier_id>^outbound_error.state=20

    The details on the customer ID, supplier ID, error type, unique import set ID, and state can be found in the Outbound Status table, which is the parent error table.

    URL format

    /api/sn_spend_intg/spendint/orderack

    Supported request parameters

    Table 1. Path parameters
    Name Description
    None
    Table 2. Query parameters
    Name Description
    mode Support for asynchronous and synchronous modes for third-party integration.

    Data type: String

    Valid values:
    • async: Asynchronous mode.
    • sync: Synchronous mode.

    Default: async
    Table 3. Request body parameters (XML or JSON)
    Name Description
    customer_id Required. Identifier for the customer.

    Data type: String

    Maximum length: 100
    order_number Required. Purchase order number provided by the customer for this order.

    Data type: String

    Maximum length: 40
    sales_order_lines List of objects that define the sales order lines with unique updates for the purchases in this order.

    Data type: Array

    "sales_order_lines":[
  {
    "estimated_arrival_date": "String",
    "line_number": "String",
    "sales_order_line_number": "String"
  }
]
    sales_order_lines.estimated_arrival_date Estimated arrival date of the order.

    Data type: String

    Maximum length: 40

    Format: YYYY-MM-DD
    sales_order_lines.line_number Required. Purchase order line number that was generated by the customer for a particular purchase.

    Data type: String

    Maximum length: 40
    sales_order_lines.sales_order_line_number Sales order line number that was generated by the supplier. This number is required only for revisions to this purchase.

    Data type: String

    Maximum length: 40
    sales_order_number Number or value that is generated by the supplier for this order.

    Data type: String

    Maximum length: 40
    status_code Required. Status of the submitted order that confirms if the order was successfully placed.

    Data type: String

    Valid values:
    • confirmed: Order placed successfully.
    • rejected: Order not placed.
    status_message Message that is attached to a status code. For example, the message could be that the order was successfully placed and is on back order.

    Data type: String

    Maximum length: 1000
    supplier_id Required. Identifier for the reseller or supplier that the customer can place orders with.

    Data type: String

    Maximum length: 100
    third_party_import_id Identifier that enables a third party to pass a string value to uniquely identify a set of imported data.

    Data type: String

    Maximum length: 100

    Headers

    The following request and response headers apply to this HTTP action only or apply to this action in a distinct way.

    Table 4. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Note:
    Only the application/json data format is supported for Procurement Integration Framework.
    Table 5. Response headers
    Header Description
    None

    Status codes

    The following status codes apply to this HTTP action.

    Table 6. Status codes
    Status code Description
    success Successful. The request was successfully processed.
    failure Unsuccessful. The request was processed with errors.

    Response body parameters (JSON)

    These response body parameters are received when queried in synchronous mode.
    Name Description
    error_response_body Description of the errors, listed by the sales order number, sales order line number, and the error message.

    Data type: Array
    error_response_body.error_message Detailed error message.

    Data type: String
    status_code Response status such as "success" or "failure."

    Data type: String

    cURL request

    curl "https://instance.service-now.com/api/sn_spend_intg/spendint/orderack" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'
{"root":[{
  "customer_id": "ACME CORP",
  "supplier_id": "SUP-123456",
  "third_party_import_id": "undefined",
  "order_number": "PO08903323",
  "sales_order_number": "SO03323212",
  "status_code": "CONFIRMED",
  "status_message": "BACKORDERED",
  "sales_order_lines":[
    {
      "line_number": "POL6789876",
      "sales_order_line_number": "SOL5678909",
      "estimated_arrival_date": "YYYY-MM-DD"
    }
  ]
}
]}

    Possible responses:

    // Success response:
{
    "result": {
        "response": "success"
    }
}

// Error response:
{
    "result": {
        "response": [
            {
                "customer_id": "ACME CORP",
                "supplier_id": "SUP-123456",
                "third_party_import_id": "undefined",
                "status_code": "failure",
                "error_response_body": [
                    {
                        "sales_order_number": "SO03323212",
                        "sales_order_line_number": "SOL5678909",
                        "error_message": "Field Value empty/Formatting issue Purchase order number\nField Value empty/Formatting issue Purchase order line number\n"
                    }
                ]
            }
        ]
    }
}