Spendint API - POST /sn_spend_intg/spendint/price

  • Release version: Xanadu
  • Updated August 1, 2024
  • 3 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/price

    The Spendint API endpoint/snspendintg/spendint/priceenables ServiceNow customers to update pricing information for supplier product records. It identifies products by SKU and updates the contract pricing if the product exists. If no matching product is found, the API returns an error. This API supports both synchronous and asynchronous modes and integrates with ServiceNow’s procurement and spend management capabilities.

    Show full answer Show less

    Request Structure and Parameters

    • Required Identifiers:
      • customerid: The customer placing the order.
      • catalogid: The catalog content identifier for purchasable items.
      • supplierid: The supplier or reseller identifier.
      • products: An array of up to 1000 products to create or update pricing for.
    • Product Details: Each product must include a unique sku and a contractagreement object, which specifies:
      • contractnumber: Active contract number (required).
      • contractstartdate and contractenddate: Contract term dates (YYYY-MM-DD format).
      • negotiatedprice and negotiatedcurrency: Unit price and currency (required).
    • Optional: thirdpartyimportid to uniquely identify imported data sets from third parties.
    • Query Parameter: mode controls asynchronous (default) or synchronous processing.

    Response Handling and Status

    When called synchronously, the response indicates success or failure with detailed error messages by SKU, helping identify issues such as missing products or data formatting problems.

    For asynchronous processing, customers can query the ServiceNow database’s Price Error table to track failed imports using parameters filtering by supplierid and error state. The Outbound Status table provides additional details like customer ID, supplier ID, and unique import set IDs.

    Practical Use and Benefits

    • Allows automated, bulk updates of supplier product pricing based on contract agreements.
    • Ensures pricing data consistency by matching SKUs to existing products.
    • Supports error tracking and troubleshooting through detailed error tables accessible via REST queries.
    • Facilitates integration with third-party procurement systems by supporting import IDs and asynchronous processing.

    Additional Notes

    • Only JSON format is supported for Procurement Integration Framework.
    • Max length constraints on string fields ensure data validity.
    • Properly formatted dates and currency values are required to avoid errors.

    Updates any pricing for supplier product records.

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

    Status tables

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

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

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

    URL format

    /api/sn_spend_intg/spendint/price

    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 products to create or update. Each transaction has a limit of 1000 products.

    Data type: Array

    "products": [
  {
    "contract_agreement": {Array},
    "sku": "String"
  }
]
    products.contract_agreement Details of the contract for a product.

    Data type: Object

    "contract_agreement": {
  "contract_end_date": "String",
  "contract_number": "String",
  "contract_start_date": "String",
  "negotiated_currency ": "String",
  "negotiated_price": "String"
}
    products.contract_agreement.contract_end_date Date on which the contract term ends.

    Data type: String

    Maximum length: 40

    Format: YYYY-MM-DD
    products.contract_agreement.contract_number Required. Number of the active contract that is associated with the product.

    Data type: String

    Maximum length: 100
    products.contract_agreement.contract_start_date Date on which the contract term starts.

    Data type: String

    Maximum length: 40

    Format: YYYY-MM-DD
    products.contract_agreement.negotiated_currency Required. Currency of the negotiated price.

    Data type: String

    Maximum length: 40
    products.contract_agreement.negotiated_price Required. Unit price of a product as negotiated through a contract with the supplier or reseller.

    Data type: String

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

    Data type: String

    Maximum length: 100
    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 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.service-now.com/api/sn_spend_intg/spendint/price" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'
{"root": [{
  "customer_id": "ACME CORP",
  "catalog_id": "AB-1234323",
  "supplier_id": "SUP-123456",
  “third_party_import_id”: “DEL789876",
  "products": [
    {
      "sku": "5578874",
      "contract_agreement": {
        "contract_number": "34567892",
        "contract_start_date": "YYYY-MM-DD",
        "contract_end_date": "YYYY-MM-DD",
        "negotiated_price": "456",
        "negotiated_currency ": "USD"
      }
    }
  ]
}
]}

    Possible responses:

    // Success response:
{
    “result”: {
        “response”: “success”
    }
}

// Error response:
{
    “result”: {
        “response”: [
            {
                “customer_id”: “ACME CORP”,
                “supplier_id”: “SUP-123456”,
                “third_party_import_id”: “DEL789876",
                “status_code”: “failure”,
                “error_response_body”: [
                    {
                        “sku”: “5578874”,
                        “error_message”: “The product for which you are trying to update pricing does not exist\nField Value empty/Formatting issue Negotiated currency\nField Value empty/Formatting issue Contract start date\nField Value empty/Formatting issue Contract end date\n”
                    }
                ]
            }
        ]
    }
}