Spendint API - POST /sn_spend_intg/spendint/availability

  • Release version: Washingtondc
  • Updated February 1, 2024
  • 2 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/availability

    The Spendint API allows customers to update the availability of supplier product records within the Procurement Service Management module. This API checks for existing supplier products using their SKU and updates the available units accordingly.

    Show full answer Show less

    Key Features

    • Product Availability Update: Updates the available units for existing supplier products.
    • Error Handling: Generates error messages if the specified product does not exist.
    • Status Tracking: Enables querying of update requests and failures via the ServiceNow database using the Table REST API.
    • Request Parameters: Supports multiple parameters including catalog ID, customer ID, and product details (SKU, available units, unit type).
    • Asynchronous and Synchronous Modes: Offers support for both integration modes, allowing flexibility in processing requests.

    Key Outcomes

    By utilizing this API, ServiceNow customers can effectively manage and update product availability, ensuring accurate inventory records. Successful execution of requests leads to updated supplier product statuses, while error handling provides insights into any issues encountered during the process.

    Updates the availability for supplier product records.

    When supplier product records are available, the API uses the product SKU to find an existing supplier product. If a matching supplier product exists, the corresponding available_units field is updated. If no matching supplier product is found, an error message generates stating that the product for which you are trying to update availability for does not exist.

    Status tables

    To know the status of the update availability request, make a REST call into the ServiceNow database using the Table REST API. The response from the API lists the records where the update availability request failed. For update availability response, query the Availability 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/availability

    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
    catalog_id Required. Identifier for the catalog content that can be purchased by a customer.

    Data type: String

    Maximum length: 100
    customer_id Required. Identifier for the customer.

    Data type: String

    Maximum length: 100
    products List of objects that define the products to update. Each transaction has a limit of 1000 products.

    Data type: Array

    "products": [
  {
    "available_units": "String",
    "sku": "String",
    "unit": "String"
  }
]
    products.available_units Required for products that are kept in stock. Number of units available for this product.

    Data type: String

    Maximum length: 40
    products.sku Required. Number that is generated by a supplier that uniquely identifies a product sold by that supplier.

    Data type: String

    Maximum length: 100
    products.unit Required. Unit or rate at which the product is sold by the supplier. For example, pieces, hours, and so on.

    Data type: String

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

    Data type: String

    Maximum length: 100
    third_party_import_id Allows 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 sku 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.servicenow.com/api/sn_spend_intg/spendint/availability" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'
{"root": [{
  "customer_id": "AB-1234323",
  "catalog_id": "ACME CORP",
  "supplier_id": "SUP-123456",
  "third_party_import_id": "DEL6789876",
  "products": [
    {
      "sku": "5578874",
      "unit": "Each",
      "available_units": "20"
    }
  ]
}
]}

    Possible responses:

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

Error response: 
{
    "result": {
        "response": [
            {
                "customer_id": "AB-1234323",
                "supplier_id": "SUP-123456",
                "third_party_import_id": "DEL6789876",
                "status_code": "failure",
                "error_response_body": [
                    {
                        "sku": "5578874",
                        "error_message": "The product for which you are trying to update availability does not exist\nField Value empty/Formatting issue Unit\n"
                    }
                ]
            }
        ]
    }
}