Spendint API - POST /sn_spend_intg/spendint/availability
Summarize
Summary of Spendint API - POST /snspendintg/spendint/availability
The Spendint API endpoint/snspendintg/spendint/availabilityallows ServiceNow customers to update the availability of supplier product records by specifying product SKUs. It ensures that only existing supplier products have theiravailableunitsfield updated. If a SKU does not correspond to an existing product, the API returns an error message.
Show less
This API supports both synchronous and asynchronous modes, enabling flexible integration with third-party systems. Customers can check update statuses by querying relevant status and error tables in the ServiceNow database using REST calls.
Key Features
- Update Availability: Modify the number of available units for specified supplier products identified by SKU.
- Validation: Returns an error if the product SKU does not exist in the supplier product records.
- Request Parameters:
- catalogid: Required identifier for the catalog content purchasable by customers.
- customerid: Required identifier for the customer.
- products: Array of up to 1000 products per request, each including
sku,unit, andavailableunits. - supplierid: Identifier for the supplier or reseller.
- thirdpartyimportid: Optional identifier for tracking imported data sets.
- mode: Query parameter to specify asynchronous (default) or synchronous processing.
- Request and Response Formats: Supports JSON format (mandatory for Procurement Integration Framework) with clear success and failure response structures.
- Status Tracking: Use the Availability Error and Outbound Status tables to monitor failed update requests and error details.
Practical Usage and Outcomes
By integrating this API, ServiceNow customers can programmatically maintain accurate inventory availability for supplier products, ensuring purchase catalog data is current. This enhances procurement accuracy and supplier collaboration.
In synchronous mode, immediate error feedback is provided per SKU, allowing rapid resolution of issues such as non-existent products or data format errors.
Asynchronous mode is suited for bulk or batched updates where immediate confirmation is not required.
Customers can query system tables to audit update statuses, identify failures, and investigate error types, facilitating robust integration and operational transparency.
Example Usage
A typical JSON request includes customer and catalog identifiers, supplier ID, optional third-party import ID, and a list of products with their SKUs, units, and available quantities. The API returns a success response or detailed error messages per product SKU if issues occur.
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
| Name | Description |
|---|---|
| None |
| Name | Description |
|---|---|
| mode | Support
for asynchronous and synchronous modes for third-party
integration. Data type: String Valid
values:
Default: async |
| 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 | 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.
| Header | Description |
|---|---|
| Accept | Data format of the response
body. Supported types: application/json or
application/xml.
Default: application/json |
| Header | Description |
|---|---|
| None |
Status codes
The following status codes apply to this HTTP action.
| 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"
}
]
}
]
}
}