Spendint API - POST /sn_spend_intg/spendint/shipment

  • Release version: Yokohama
  • Updated January 30, 2025
  • 5 minutes to read

    • Use this endpoint to accept updates on purchases from third parties.

    When you receive data, you must match the shipment data to a purchase order line by using the sales order line number. You can use the tracking number to find an existing shipment detail record that is related to the purchase order line. If no such record is found, create a new shipment detail record. If no purchase order or purchase order line exists for the shipment data, you see an error message that states that the purchase order for this shipment does not exist.
    Note:
    If the purchase order and purchase order lines are in the Pending Submission status, and the sales order and sales order lines are not populated, then the shipment and invoice posting from the third-party reseller is not allowed. It is only allowed when the status of the purchase order and purchase order lines are Ordered. Also, there is no sequential restriction on shipment and invoice posting.

    Status tables

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

    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 Identifier for the customer.

    Data type: String

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

    Data type: String

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

    Data type: String

    Maximum length: 40
    shipment_lines List of shipment lines that can contain the serial number, IMEI number, and asset tag details of the assets.

    Data type: Array

    "shipment_lines": [
  {
    "actual_shipment_date": "String",
    "estimated_arrival_date": "String",
    "line_number": "String",
    "planned_shipment_date": "String",
    "product_details": [Array],
    "sales_order_line_number": "String",
    "shipping_address": {Object},
    "shipping_carrier": "String",
    "shipment_quantity": "String",
    "ship_to": "String",
    "tracking_number": "String"
  }
]
    shipment_lines.actual_shipment_date Date on which the shipment leaves the supplier’s location.

    Data type: String

    Maximum length: 40

    Format: YYYY-MM-DD
    shipment_lines.estimated_arrival_date Date on which the shipment is expected to arrive at the specified location.

    Data type: String

    Maximum length: 40

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

    Data type: String

    Maximum length: 40
    shipment_lines.planned_shipment_date Date on which the shipment is planned to leave the supplier’s location.

    Data type: String

    Maximum length: 40

    Format: YYYY-MM-DD
    shipment_lines.product_details List of objects that define the details about the products being shipped. Options include the serial number, IMEI number, and asset tag details.

    Data type: Array

    "product_details": [
  {
    "asset_tag": "String",
    "imei": "String",
    "serial_number": "String"
  }
]
    shipment_lines.product_details.asset_tag Asset tag of the shipped product.

    Data type: String

    Maximum length: 100
    shipment_lines.product_details.imei IMEI number of the shipped product.

    Data type: String

    Maximum length: 100
    shipment_lines.product_details.serial_number Required. Serial number of the shipped product.

    Data type: String

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

    Data type: String

    Maximum length: 40
    shipment_lines.shipping_address Address where the products are being shipped to.

    Data type: Object

    "shipping_address":
  {
    "city": "String",
    "country": "String",
    "name": "String",
    "state": "String",
    "street": "String",
    "zip_code": "String"
  }
    shipment_lines.shipping_address.city Name of the city where the products are shipped to.

    Data type: String

    Maximum length: 1000
    shipment_lines.shipping_address.country Country where the products are shipped to.

    Data type: String

    Maximum length: 40
    shipment_lines.shipping_address.name Name of the customer that the products are being shipped to.

    Data type: String

    Maximum length: 1000
    shipment_lines.shipping_address.state State where the products are shipped to.

    Data type: String

    Maximum length: 1000
    shipment_lines.shipping_address.street Name of the street where the products are shipped to.

    Data type: String

    Maximum length: 1000
    shipment_lines.shipping_address.zip_code Zip code or pin code where the products are shipped to.

    Data type: String

    Maximum length: 40
    shipment_lines.shipment_quantity Required. Number of the products being shipped as physical goods. The number should contain the quantity of the products that are in the shipment.

    Data type: String

    Maximum length: 40
    shipment_lines.shipping_carrier Shipping carrier that is delivering the product to the specified location such as FedEx, UPS, USPS, and so on.

    Data type: String

    Maximum length: 100
    shipment_lines.ship_to Name of the recipient that the products are shipped to.

    Data type: String

    Maximum length: 100
    shipment_lines.tracking_number Tracking number that is provided by the shipping carrier for the whole or a portion of the purchase.

    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
    supplier_shipment_number Required. Identification number that is generated for this shipment. Typically, this number is generated by an Enterprise Resource Planning (ERP) or order tracking system.

    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 line number, sales order number, supplier shipment 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/shipment" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'
{"root":[{
  "customer_id" : "ACME CORP",
  "supplier_id" : "SUP-123456",
  "third_party_import_id": "DEL2134324",
  "supplier_shipment_number" : "TN-YU67898723",
  "order_number": "PO0001002",
  "sales_order_number": "SO00223002",
  "shipment_lines": [
    {
      "line_number": "POL0001005",
      "sales_order_line_number": "SOL0231325",
      "shipment_quantity": "4",
      "shipping_carrier": "FedEx",
      "tracking_number": "E-901290092",
      "shipping_address":
        {
          "name" : "1640 Camino Del Rio North #202, San Diego,CA",
          "street" : "1640 Camino Del Rio North",
          "city" : "San Diego",
          "state" : "CA",
          "zip_code" : "92108-1512",
          "country" : "US"
        },
      "ship_to": "John doe",
      "planned_shipment_date": "YYYY-MM-DD",
      "actual_shipment_date": "YYYY-MM-DD",
      "estimated_arrival_date": "YYYY-MM-DD",
      "product_details": [
        {
          "serial_number": "FL1234-23242319001",
          "imei": "2134890294",
          "asset_tag": ""
        },{
          "serial_number": "FL1234-23242319110",
          "imei": "245499003",
          "asset_tag": ""
        }
      ]
    }
  ]
}
]}

    Possible responses:

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

// Error response:
{
    "result": {
        "response": [
            {
                "customer_id": "ACME CORP",
                "supplier_id": "SUP-123456",
                "third_party_import_id": "DEL2134324",
                "status_code": "failure",
                "error_response_body": [
                    {
                        "sales_order_line_number": "SOL0231325",
                        "sales_order_number": "SO00223002",
                        "supplier_shipment_number": "TN-YU67898723",
                        "error_message": "The purchase order for this shipment does not exist\nThe purchase order line for this shipment does not exist\n"
                    }
                ]
            }
        ]
    }
}