--- sourceDocument: Yokohama Finance and Supply Chain sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/yokohama/source-to-pay-operations Release : - yokohama ft:locale : - en-US ft:publication_title : - Yokohama Finance and Supply Chain ft:clusterId : - stpop bundleId : - stpop workflow : - Employee --- # Spendint API - POST /sn_spend_intg/spendint/catalog # Spendint API - POST /sn_spend_intg/spendint/catalog {#ariaid-title1} * Release version: Yokohama * * Updated January 30, 2025 * * ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 8 minutes to read Allows suppliers to post multiple catalogs for creating supplier products, model products, contracts, and pricing records. In the catalog API integration, when you receive data from a third-party catalog, you can: 1. Create any new third-party categories and map these categories to model categories. * If available, use the United Nations Standard Products and Services Code (UNSPSC) and then the category name. * If UNSPSC is not available, use just the category name. {#spendint-POST-catalog__ul_jds_5yl_kmb} 2. After you map a third-party category to a model category, use the Manufacturer Part Number (MPN) to find an existing product model, if one is available. 1. If a product model is found for the MPN, update the product model with any changes, and then create or update any supplier products that are related to the product model. 2. If a product model does not exist for the MPN, do the following: 1. A product model class is usually available on the model category that is referenced by the third-party category for the product. Use this product model class to get the product model table in which the product model should be created, for example, hardware, software, consumable, and so on. If no product model class is available, create the product model in the base product model table. 2. After the correct product model class is identified, create a new product model in the correct class as follows: * Manufacturer, publisher, or provider should map to the manufacturer on the product model. * Product name from the API should map to the name on the product model. * MPN from the API should update the model number. * Product description from the API should update the description on the product model. * Model category should be updated with the product category referenced on the third-party category record. * Product category should be updated with the product category referenced on the third-party category record. * If there are values in the substitute products in the API, create the substitute product records between the current product model and the other product models. * If there are values in the compatible products in the API, create the compatible product records between the current product model and the other product models. * Product attributes from the API should be created or updated in the product attribute related list for the product model. {#spendint-POST-catalog__ul_wvr_jdk_mnb} {#spendint-POST-catalog__ol_trv_qck_mnb} {#spendint-POST-catalog__ol_rtb_hck_mnb} 3. If a product model is available, use the supplier part number to create or update the supplier products that are related to the product model. {#spendint-POST-catalog__ol_oqw_3dd_dmb} ## Third-party mapping {#spendint-POST-catalog__section_w4v_nfn_n4b} Use the following tables to perform the third-party category, model, and unit mappings: * Third-Party Categories: Stores all the third-party category records for the ShoppingHub administrator to map with internal existing model categories. * Third-Party Model Mappings: Stores all the mapping information between product models and third-party model categories. * Third-Party Units: Stores all the third-party unit records for the ShoppingHub administrator to map with supplier product units. * Third-Party Unit Mappings: Stores all the mapping information between product models and third-party units. {#spendint-POST-catalog__ul_mgg_dbt_knb} Note: A third-party integration product is auto-published when both the third-party category and third-party unit are mapped appropriately. ## Supplier product sales dates {#spendint-POST-catalog__section_mxc_phn_n4b} A supplier product is discontinued and no longer published in the catalog when it has reached its sales end date. The Sales start date and Sales end date fields on the Supplier product form are populated through third-party integration from theCatalog API. ## Status tables {#spendint-POST-catalog__section_hrm_qts_knb} To know the status of the bulk product 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 bulk import request failed. For bulk product import response, query the Catalog Error table with the following parameter: `sysparm_query=outbound_error.supplier_id=^outbound_error.state=20` 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/catalog ## Supported request parameters {#spendint-POST-catalog__entry__2} | Name | Description | |-|-| | None | | [Table 1. Path parameters] {#spendint-POST-catalog__entry__6} | Name | Description | |-|-| | mode | Support for asynchronous and synchronous modes for third-party integration. Data type: String Valid values: * async: Asynchronous mode. * sync: Synchronous mode. {#spendint-POST-catalog__ul_hdr_tkg_ymb} Default: async | [Table 2. Query parameters] {#spendint-POST-catalog__entry__10} | Name | Description | |-|-| | customer_id | Identifier for the customer. Data type: String Maximum length: 100 | | catalog_id | Identifier for the catalog content that can be purchased by a 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": [ { "available_units": "String", "available_for_country": [Array], "bundled_components": [Array], "contract_agreement": {Object}, "delivery_time": "String", "images": [Array], "manufacturer": "String", "mpn": "String", "parent_bundle": "String", "product_attributes": {Object}, "product_category_name": "String", "product_description": "String", "product_name": "String", "sku": "String", "unit": "String", "unspsc": "String", } ] | | products.available_units | Required for products that are kept in stock. This value indicates the quantity of units that are available for this product. Data type: String Maximum length: 40 | | products.available_for_country | List of country codes where the supplier product can be purchased. If no country is provided, a user from any country can purchase the product. Data type: Array "available_for_country": ["US","IN","GB"] | | products.bundled_components | Valid only for scenarios when sending a product bundle as part of the catalog payload, and applicable only for the parent bundle payloads. This value contains the reference to the child bundle components. The list of the MPN and quantities for the child bundle components are maintained here. Note: Since the same child bundle component can be added more than once within a bundle, the entered quantity is the differentiator between the same children bundle components. The child bundle components and their details (MPN and quantities) should be mapped to the same supplier. Data type: Array "bundled_components": [ { "mpn": "String", "quantity": "String" } ] | | products.contract_agreement | Details of the contract for a product. Note: This is not required for child bundle components. 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.delivery_time | Estimated number of days it takes to ship a product to the customer. This value must represent the number of days and be a whole integer. Data type: String Maximum length: 40 | | products.images | List of strings that specify the image URLs for the supplier product. Data type: Array | | products.manufacturer | Required. Company that manufactures, publishes, or provides the product. This is not the supplier or reseller of the product. Data type: String Maximum length: 100 | | products.mpn | Required. Identifier for a product that is provided by the manufacturer, publisher, or provider. Note: This is not required for reseller parent bundles if the SKU value is available. Data type: String Maximum length: 100 | | products.parent_bundle | Valid only for scenarios when sending a product bundle as part of the catalog payload, and applicable only for the child bundle component payloads. In the case of a child bundle component, the reference to the parent is maintained here. The parent MPN and SKU values are also set here. Data type: String Maximum length: 100 | | products.product_attributes | List of key-value pairs that define product attributes, for example, `"Color": "Space Grey"`. Multiple attributes for a product are allowed. However, only those attributes that impact pricing or stock availability should be provided through the API. Data type: Object | | products.product_category_name | Required. Name that you enter if you are not setting the unspsc property. This name is the category to which a product belongs. This category name can be used in a commerce scenario to shop for the product. For example, a power strip product could belong to an Office Equipment category. Data type: String Maximum length: 100 | | products.product_description | Full description of the product that appears to a shopper within a commerce experience. Note: It is recommended that the supplier be as descriptive as possible here, especially for product bundle catalog items where there are child bundle components. Data type: String Maximum length: 65000 | | products.product_name | Required. Name of the product. Data type: String Maximum length: 1000 | | 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 | | 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: 40 | | products.unspsc | Required. Identifier that you enter if you are not setting the product_category_name property. This identifier is the UNSPSC for the category to which a product belongs. For example, UNSPSC code 43210000 is the identifier for the product category Computers. Data type: String Maximum length: 100 | | supplier_id | Required. Identifier for the reseller or supplier with whom the customer can place orders. 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 | [Table 3. Request body parameters (XML or JSON)] ## Headers The following request and response headers apply to this HTTP action only or apply to this action in a distinct way. {#spendint-POST-catalog__entry__64}{#spendint-POST-catalog__accept-RESTAPI} | Header | Description | |-|-| | Accept | Data format of the response body. Supported types: application/json or application/xml. Default: application/json | [Table 4. Request headers] Note: Only the application/json data format is supported for Procurement Integration Framework. {#spendint-POST-catalog__entry__68} | Header | Description | |-|-| | None | | [Table 5. Response headers] ## Status codes The following status codes apply to this HTTP action. {#spendint-POST-catalog__table_lml_1qg_ymb__entry__2} | Status code | Description | |-|-| | success | Successful. The request was successfully processed. | | failure | Unsuccessful. The request was processed with errors. | [Table 6. Status codes] {#spendint-POST-catalog__table_lml_1qg_ymb} ## Response body parameters (JSON) These response body parameters are received when queried in synchronous mode.{#spendint-POST-catalog__entry__78} | Name | Description | |-|-| | error_response_body | Description of the errors, listed by sku, mpn, 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/catalog" \ --request POST \ --header "Accept:application/json" \ --user 'username':'password' {"root": [{ "customer_id": "AB-1234323", "catalog_id": "ACME CORP-12347898", "supplier_id": "SUP-123456", "third_party_import_id": "DELL1234567", "products": [ { "product_name": "Apple MacBook Pro 13 Core i7", "mpn": "Z0WQ-20004301931", "sku": "55788741", "manufacturer": "Apple", "product_category_name": "Computer", "parent_bundle": "920-0045362002", "bundled_components": { "mpn": "Z0WQ-20004301931", "quantity": "4", }, "unspsc": "43211500", "product_description": "Apple MacBook Pro 13 Core i7 2.8GHz 16GB 512GB - Touch Bar - Space Gray", "product_attributes": { "Color": "Space Grey", "RAM": "16GB", "Screen Size": "13inch" }, "images": ["http://test123.image1.png", "http://test123.image2.jpeg"], "unit": "Each", "available_units": "4", "available_for_country": ["US","IN","GB"], "delivery_time": "4", "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": "AB-1234323", "supplier_id": "SUP-123456", "third_party_import_id": "DELL1234567", "status_code": "failure", "error_response_body": [ { "sku": "55788741", "mpn": "Z0WQ-20004301931", "error_message": "Field Value empty/Formatting issue Negotiated currency \n" } ] } ] } }