Order API

Release version: Washingtondc

Updated November 21, 2024

25 minutes to read

The Order API enables retrieving and creating orders with order line items for the Customer Service Management (CSM) application.

This API requires the Order Management for Customer Service Management (app-csm-order-mgmt) store application and is provided within the sn_ind_tmt_orm namespace. For information, see Sales and Order Management.

This API requires sn_csm_om.order_integrator for access, and one of the following:

sn_csm_om.consumer_agent – API write access restricted to B2C orders.
sn_csm_om.customer_agent – API write access restricted to B2B orders.
sn_csm_om.order_admin – API write access for B2B or B2C orders.

For information on B2B and B2C orders, see Customer Data Models for B2B2C.

Order API – GET /sn_ind_tmt_orm/order/{id}

Retrieves complete order details by specifying the sys_id or order number.

URL format

Versioned URL: /api/sn_ind_tmt_orm/{api_version}/order/{id}

Default URL: /api/sn_ind_tmt_orm/order/{id}

Supported request parameters

Table 1. Path parameters
Name	Description
api_version	Optional. Version of the endpoint to access. For example, `v1` or `v2`. Only specify this value to use an endpoint version other than the latest. Data type: String
id	Sys_id or order number (order_id) of the record to retrieve located in the Orders [sn_csm_om_order] table. Data type: String

Table 2. Query parameters
Name	Description
sysparm_display_value	Flag that indicates whether to show the display value of the reference fields. Valid values: true: Show the display value of the reference fields, choice fields, and date field in the response. false: Show the actual value of the reference fields, choice fields, and date field in the response. Default: false

Table 3. Request body parameters (XML or JSON)
Name	Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 4. Request headers
Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json

Table 5. Response headers
Header	Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Table 6. Status codes
Status code	Description
200	Successful. The request was successfully processed.
401	The user is not authenticated.
403	The user is not authorized. The user does not have required roles to access the API. The user does not have authorization to read the order. This API requires sn_csm_om.order_integrator for access, and one of the following: sn_csm_om.consumer_agent – API write access restricted to B2C orders. sn_csm_om.customer_agent – API write access restricted to B2B orders. sn_csm_om.order_admin – API write access for B2B or B2C orders.

Response body parameters (JSON or XML)


Name	Description
account	Sys_id of a record located in the Accounts [customer_account] table. Identifies the account for B2B orders. Data type: String
actual_end_date	End date of order. Format: UTC format, yyyy-MM-dd HH:mm:ss Data type: String
actual_start_date	Start date of order. Format: UTC format, yyyy-MM-dd HH:mm:ss Data type: String
billing_city	Name of the billing city. Data type: String
billing_country	Abbreviation of the billing country. Data type: String
billing_state	Abbreviation of the billing state or province. Data type: String
billing_street	Billing street address. Data type: String
billing_zip	Billing ZIP or postal code. Data type: String
comments	Additional information for the order. Data type: String
consumer	Sys_id of a record located in the Consumers [csm_consumer] table. Identifies the consumer for B2C orders. Data type: String
contact	Sys_id of the customer contact related to the account. Listed in the Contacts [customer_contact] table. Data type: String
contract	Sys_id of the Customer Service contract listed in the Contracts [ast_contract] table. Data type: String
error	Details describing an error encountered during the request process. Data type: Object `"error": { "detail": "String", "message": "String" }`
error.detail	Details of the error encountered during the request process. Data type: String
error.message	Message for the error encountered during the request process. Each error message has a corresponding description in the detail property. Data type: String
expected_end_date	Expected end date of order. Format: UTC format, yyyy-MM-dd HH:mm:ss Data type: String
expected_start_date	Expected start date of order. Format: UTC format, yyyy-MM-dd HH:mm:ss Data type: String
external_id	External ID representing a related record on a third party's system. Data type: String
external_system	Name of the customer's system. Data type: String
order_category	Customer order type. Possible values: product service Data type: String
order_currency	Currency code representing the currency in which the order was purchased. For example, `USD` for United States Dollars. This currency is used for all amount fields in the order and line orders. Currency codes are listed in the Currencies [fx_currency] table. Note: This property might not be available in earlier versions of Order Management. Data type: String
order_date	Date and time of order creation. Format: UTC format, yyyy-MM-dd HH:mm:ss Data type: String
order_id	Order number of the order listed in the Orders [sn_csm_om_order] table. Data type: String
order_line_items	Required. List of objects that define each order line item in the order. Located in the Order Line Items [sn_csm_om_order_line_item] table. Data type: Array Required properties in each order line item object: account for B2B orders or consumer for B2C orders. product_offering – quantity unit_of_measurements order_line_characteristics "order_line_items": [ { "account": "String", "action": "String", "comments": "String", "consumer": "String", "contact": "String", "delivered_quantity": "String", "effective_date": "String", "expiration_date": "String", "external_id": "String", "external_system": "String", "list_price": "String", "location": "String", "order_line_characteristics": [Array], "order_line_id": "String", "order": "String", "parent_line_item": "String", "previous_product_model": "String", "price_list": "String", "product_offering": "String", "product_specification": "String", "product": "String", "quantity": "String", "shipping_city": "String", "shipping_country": "String", "shipping_state": "String", "shipping_street": "String", "shipping_zip": "String", "short_description": "String", "sku": "String", "sold_product": "String", "specification": "String", "state": "String", "status": "String", "sys_class_name": "String", "sys_created_by": "String", "sys_created_on": "String", "sys_id": "String", "sys_mod_count": "String", "sys_tags": "String", "sys_updated_by": "String", "sys_updated_on": "String", "top_line_item": "String", "total_price": "String", "unit_of_measurement": "String", "unit_price": "String", "work_notes": "String" } ]
order_line_items	List of objects that define each order line item in the order. Located in the Order Line Items [sn_csm_om_order_line_item] table. Data type: Array "order_line_items": [ { "account": "String", "action": "String", "comments": "String", "consumer": "String", "contact": "String", "delivered_quantity": "String", "effective_date": "String", "expiration_date": "String", "external_id": "String", "external_system": "String", "list_price": "String", "location": "String", "order_line_characteristics": [Array], "order_line_id": "String", "order": "String", "parent_line_item": "String", "previous_product_model": "String", "price_list": "String", "product_offering": "String", "product_specification": "String", "product": "String", "quantity": "String", "shipping_city": "String", "shipping_country": "String", "shipping_state": "String", "shipping_street": "String", "shipping_zip": "String", "short_description": "String", "sku": "String", "sold_product": "String", "specification": "String", "state": "String", "status": "String", "sys_class_name": "String", "sys_created_by": "String", "sys_created_on": "String", "sys_id": "String", "sys_mod_count": "String", "sys_tags": "String", "sys_updated_by": "String", "sys_updated_on": "String", "top_line_item": "String", "total_price": "String", "unit_of_measurement": "String", "unit_price": "String", "work_notes": "String" } ]
order_line_items.account	Required for B2B orders. Sys_id of the business account assigned to this order line item. Located in the Accounts [customer_account] table. The consumer property is required for B2C orders. Data type: String
order_line_items.account	Sys_id of the business account assigned to this order line item. Located in the Accounts [customer_account] table. Data type: String
order_line_items.action	Action that determines how the order line is added to the order. Possible values: add change Data type: String
order_line_items.comments	Additional information for the order line item. Data type: String
order_line_items.consumer	Sys_id of the consumer assigned to this order line item. Located in the Consumers [csm_consumer] table. Data type: String
order_line_items.contact	Contact sys_id related to the account. Data type: String
order_line_items.delivered_quantity	Number of items in the order delivered. Data type: String
order_line_items.effective_date	Effective date of order line. Format: yyyy-MM-dd HH:mm:ss in UTC time zone Data type: String
order_line_items.expiration_date	Expiration date of order line. Format: yyyy-MM-dd HH:mm:ss in UTC time zone Data type: String
order_line_items.external_id	External ID of the order line item. Data type: String
order_line_items.external_system	External sys_id of the order line item. Data type: String
order_line_items.list_price	List price of the product offering per unit. Note: This property might not be available in earlier versions of Order Management. Data type: String
order_line_items.location	Sys_id of a shipping location listed in the Locations [cmn_location] table. Data type: String
order_line_items.order	This line item's order number as listed in the Orders [sn_csm_om_order] table. Data type: String
order_line_items. order_line_characteristics	List of objects defining associated order line characteristics. Order line characteristics are located in the Order Line Characteristics [sn_csm_om_order_characteristic_value] table. `"order_line_characteristics": [ { "characteristic": "String", "characteristic_option": "String" } ]` Data type: Array
order_line_items.order_line_characteristics.characteristic_option	Product characteristic unique option that triggers the exclusion rule. For example, product size or color. Data type: String
order_line_items. order_line_characteristics. characteristic_option_value	Value of a characteristic option. Data type: String
order_line_items. order_line_characteristics. external_id	External ID of the order line characteristic. Data type: Object
order_line_items. order_line_characteristics. number	Order line characteristic number listed in the Order Line Characteristics [sn_csm_om_order_characteristic_value] table. Data type: String
order_line_items. order_line_characteristics. order_line_item	Sys_id of this characteristic's order line item in the Order Line Items [sn_csm_om_order_line_item] table. Data type: String
order_line_items. order_line_characteristics. previous_characteristic_option_value	Name of the previous characteristic option associated with product model in the order line. Data type: Object
order_line_items. order_line_characteristics.specification	Service specification that is associated with the service order characteristic. Data type: String
order_line_items. order_line_characteristics. sys_class_name	System name of the table in which this order line characteristic record is located. Data type: String
order_line_characteristics. sys_created_by	System name of the user who created this record. Data type: String
order_line_items. order_line_characteristics. sys_created_on	Date and time at which the record was originally created. Data type: String
order_line_items. order_line_characteristics. sys_domain	Domain scope in which the order record is accessible. For example, global. Data type: String
order_line_items. order_line_characteristics. sys_domain_path	Domain path for the record. Data type: String Default: / (global)
order_line_items. order_line_characteristics. sys_id	Sys_id of the order record located in the Order Line Characteristics [sn_csm_om_order_characteristic_value] table. Data type: String
order_line_items. order_line_characteristics. sys_mod_count	Number of times this record has been modified. Data type: String
order_line_items. order_line_characteristics. sys_tags	System tags for the content. Data type: String
order_line_items. order_line_characteristics. sys_updated_by	System name of the user who most recently updated this record. Data type: String
order_line_items. order_line_characteristics. sys_updated_on	Date and time at which the record was most recently updated. Data type: String
order_line_items. order_line_characteristics.type	Type of order line characteristic. Possible values: product service Data type: String
order_line_items.order_line_id	Order number of the order associated with this order line item. Data type: String
order_line_items.parent_line_item	If applicable, identifies a parent line item to this line item. Data type: String
order_line_items.previous_product_model	Identifies the product model for the product listed prior to this item in the order line. Sys_id of the product listed in the Product Models [cmdb_model] table. Data type: String
order_line_items.price_list	Sys_id of a price list record in the Price Lists [sn_csm_pricing_price_list] table. Note: This property might not be available in earlier versions of Order Management. Data type: String
order_line_items.product	Sys_id of the product listed in the Product Models [cmdb_model] table. Data type: String
order_line_items.product_offering	Sys_id of the product listed in the Product Offerings [sn_prd_pm_product_offering] table. Data type: String
order_line_items.product	Sys_id of the product model listed in the Product Models [cmdb_model] table. Must be provided with matching order line item Data type: String
order_line_items.product_specification	Sys_id of the product specification associated with the order line item. Listed in the Product Specifications [sn_prd_pm_product_specification] table. Data type: String
order_line_items.quantity	Number of product models ordered. Data type: String
order_line_items.shipping_city	Name of the destination city. Data type: String
order_line_items.shipping_country	Abbreviation of the destination country. Data type: String
order_line_items.shipping_state	Abbreviation of the destination state or province. Data type: String
order_line_items.shipping_street	Destination street address. Data type: String
order_line_items.shipping_zip	Destination ZIP or postal code. Data type: String
order_line_items.short_description	Short description of the order line item. Data type: String
order_line_items.sku	Number that is generated by a supplier that uniquely identifies a product that is sold by that supplier. Data type: String
order_line_items.sold_product	Sys_id of an install base sold product listed in the Sold Products [sn_install_base_sold_product] table. Data type: String
order_line_items.specification	Specification of order line item. Data type: String
order_line_items.state	State of order line. For example, draft, new, in_progress, or completed. Data type: String
order_line_items.status	Status of the order line item. Possible values: success failure Data type: String
order_line_items.sys_class_name	System name of the table in which this order line item record is located. Data type: String
order_line_items.sys_created_by	System name of the user who created this record. Data type: String
order_line_items.sys_created_on	Date and time at which the record was originally created. Data type: String
order_line_items.sys_domain	Domain scope in which the order record is accessible. For example, global. Data type: String
order_line_items.sys_domain_path	Domain path for the record. Data type: String Default: / (global)
order_line_items.sys_id	Sys_id of the line item record located in the Order Line Items [sn_csm_om_order_line_item] table. Data type: String
order_line_items.sys_mod_count	Number of times this record has been modified. Data type: String
order_line_items.sys_tags	System tags for the content. Data type: String
order_line_items.sys_updated_by	System name of the user who most recently updated this record. Data type: String
order_line_items.sys_updated_on	Date and time at which the record was most recently updated. Data type: String
order_line_items.top_line_item	Total price of all order line items accumulated in this order. Data type: String
order_line_items.total_price	Total price of order line. The API does not calculate the total based on net price and quantity. Data type: String
order_line_items.unit_of_measurement	Sys_id for the ordered unit of measure listed in the Unit of Measures [sn_prd_pm_uom] table. Note: This property might not be available in earlier versions of Order Management. Data type: String
order_line_items.unit_of_measurement	Required. Sys_id for the ordered unit of measure listed in the Unit of Measures [sn_prd_pm_uom] table. Note: This property might not be available in earlier versions of Order Management. Data type: String
order_line_items.unit_price	Net price of the product offering per unit listed in the Currency Instances [fx_currency_instance] table. Data type: String
order_line_items.work_notes	Free-form internal work notes for the order line item. Data type: String
order_type	Order action that determines how the order is added. Possible values: add change Data type: String
partner	For B2B orders, sys_id of the associated partner for an account listed in the Accounts [customer_account] table. Data type: String
partner_contact	For B2B orders, sys_id of the primary contact of the partner for the partner account. Listed in the Contacts [customer_contact] table. Data type: String
payment_ref_id	Unique identifier of the payment. For example, check number. Data type: String
price_list	Sys_id of the associated price list listed in the Price Lists [sn_csm_pricing_price_list] table. The price is not calculated based on net price and quantity by this API. Note: This property might not be available in earlier versions of Order Management. Data type: String
quote_id	Unique ID for the order price quote. Data type: String
same_as_shipping_address	Flag that indicates whether the address of the purchaser is the same as the shipping address. Valid values: true: Address of the purchaser is the same as the shipping address. false: Address of the purchaser is different from the shipping address. Data type: Boolean
shipping_city	Name of the destination city. Data type: String
shipping_country	Abbreviation of the destination country. Data type: String
shipping_location	Sys_id of a shipping location listed in the Locations [cmn_location] table. Data type: String
shipping_state	Abbreviation of the destination state or province. Data type: String
shipping_street	Destination street address. Data type: String
shipping_zip	Destination ZIP or postal code. Data type: String
short_description	Short description of the order. Data type: String
special_instructions	Special instructions for the order. Data type: String
state	State of the order. For example, new, in_progress, or completed. Data type: String
status	Status of the order. Possible values: success failure Data type: String
sys_class_name	System name of the table in which this order record is located. Data type: String
sys_created_by	System name of the user who created this record. Data type: String
sys_created_on	Date and time at which the record was originally created. Data type: String
sys_domain	Domain scope in which the order record is accessible. For example, global. Data type: String
sys_domain_path	Domain path for the record. Data type: String Default: / (global)
sys_id	Sys_id of the order listed in the Orders [sn_csm_om_order] table. Data type: String
sys_mod_count	Number of times this record has been modified. Data type: String
sys_tags	System tags for the content. Data type: String
sys_updated_by	System name of the user who most recently updated this record. Data type: String
sys_updated_on	Date and time at which the record was most recently updated. Data type: String
total_amount	Total cost for the entire order. Data type: String

cURL request

The following example shows how to get an order by its order number.

curl "https://instance.service-now.com/api/sn_ind_tmt_orm/order/ORD0001034" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

Response:

{
  "result": {
    "actual_start_date": "",
    "payment_ref_id": null,
    "shipping_city": null,
    "channel": "api",
    "expected_end_date": "",
    "sys_updated_on": "2022-03-30 21:59:41",
    "price_list": null,
    "sys_updated_by": "username",
    "sys_created_on": "2022-03-30 21:59:41",
    "contact": "96d0461553ab70101aaeddeeff7b120b",
    "sys_domain": "global",
    "state": "draft",
    "order_type": "add",
    "sys_created_by": "eseruser",
    "shipping_street": null,
    "special_instructions": null,
    "contract": null,
    "quote_id": null,
    "expected_start_date": "",
    "sys_domain_path": "/",
    "billing_street": null,
    "billing_city": null,
    "total_amount": "2000",
    "order_id": "ORD0001034",
    "shipping_country": "USA",
    "status": "new",
    "short_description": null,
    "shipping_state": null,
    "external_id": null,
    "sys_class_name": "sn_csm_om_order",
    "sys_id": "24fdf5bd75eec510f877f30c01a15aa0",
    "shipping_zip": null,
    "billing_state": null,
    "billing_zip": null,
    "same_as_shipping_address": "0",
    "consumer": null,
    "comments": "",
    "order_currency": "USD",
    "billing_country": "USA",
    "sys_mod_count": "1",
    "billing_location": null,
    "shipping_location": null,
    "sys_tags": "",
    "order_date": "2022-03-30 21:59:41",
    "order_category": "product",
    "actual_end_date": "",
    "partner": null,
    "partner_contact": null,
    "account": "c480021553ab70101aaeddeeff7b120f",
    "external_system": null,
    "order_line_items": [
      {
        "short_description": null,
        "shipping_state": "CA",
        "shipping_city": "Santa Clara",
        "product_offering": "2d4376760f740110603bf634a7767e46",
        "external_id": null,
        "sys_updated_on": "2022-03-30 21:59:41",
        "expiration_date": "",
        "sys_class_name": "sn_csm_om_order_line_item",
        "sold_product": null,
        "sys_id": "ecfdf5bd75eec510f877f30c01a15aa3",
        "unit_of_measurement": "cb2795d553020110286eddeeff7b12ff",
        "price_list": null,
        "sys_updated_by": "username",
        "shipping_zip": "94560",
        "sys_created_on": "2022-03-30 21:59:41",
        "contact": "96d0461553ab70101aaeddeeff7b120b",
        "sys_domain": "global",
        "effective_date": "",
        "action": "add",
        "order_line_id": "ORDL0001060",
        "state": "draft",
        "sku": null,
        "consumer": null,
        "sys_created_by": "username",
        "order": "24fdf5bd75eec510f877f30c01a15aa0",
        "previous_product_model": null,
        "shipping_street": "222 Star St",
        "product": "561dba7e0f740110603bf634a7767ebe",
        "quantity": "1",
        "comments": "",
        "total_price": "2000",
        "parent_line_item": null,
        "sys_mod_count": "1",
        "specification": "104f66720f740110603bf634a7767e7d",
        "list_price": "2000",
        "unit_price": "2000",
        "sys_domain_path": "/",
        "sys_tags": "",
        "delivered_quantity": null,
        "top_line_item": null,
        "product_specification": "104f66720f740110603bf634a7767e7d",
        "location": null,
        "work_notes": "",
        "shipping_country": "USA",
        "account": "c480021553ab70101aaeddeeff7b120f",
        "external_system": null,
        "status": "new",
        "order_line_characteristics": [
          {
            "characteristic_option": "1c6ceabe0f340110603bf634a7767e97",
            "sys_mod_count": "0",
            "specification": "104f66720f740110603bf634a7767e7d",
            "external_id": null,
            "sys_updated_on": "2022-03-30 21:59:41",
            "type": "1",
            "sys_domain_path": "/",
            "sys_tags": "",
            "characteristic": "4e76f1b20fb00110603bf634a7767ee3",
            "sys_class_name": "sn_csm_om_order_characteristic_value",
            "previous_characteristic_option_value": null,
            "number": "ORC000001041",
            "sys_id": "acfd79bd75eec510f877f30c01a15a94",
            "sys_updated_by": "username",
            "sys_created_on": "2022-03-30 21:59:41",
            "sys_domain": "global",
            "characteristic_option_value": "1.2 cu",
            "order_line_item": "ecfdf5bd75eec510f877f30c01a15aa3",
            "sys_created_by": "user"
          },
          {
            "characteristic_option": "2d0d66fe0f340110603bf634a7767ef6",
            "sys_mod_count": "0",
            "specification": "104f66720f740110603bf634a7767e7d",
            "external_id": null,
            "sys_updated_on": "2022-03-30 21:59:41",
            "type": "1",
            "sys_domain_path": "/",
            "sys_tags": "",
            "characteristic": "11e639b20fb00110603bf634a7767e17",
            "sys_class_name": "sn_csm_om_order_characteristic_value",
            "previous_characteristic_option_value": null,
            "number": "ORC000001042",
            "sys_id": "e0fd79bd75eec510f877f30c01a15a95",
            "sys_updated_by": "username",
            "sys_created_on": "2022-03-30 21:59:41",
            "sys_domain": "global",
            "characteristic_option_value": "Stainless steel",
            "order_line_item": "ecfdf5bd75eec510f877f30c01a15aa3",
            "sys_created_by": "user"
          }
        ]
      }
    ]
  }
}

Order API – POST /sn_ind_tmt_orm/order

Creates a new order with line items and characteristics.

Orders with line items are defined using request body parameters. The following properties are required in most versions of Order Management:

account for B2B orders or consumer for B2C orders.
- account – Sys_id of a record located in the Accounts [customer_account] table.
- consumer – Sys_id of a record located in the Consumers [csm_consumer] table.
order_currency – Currency code representing the currency in which the order was purchased. For example, USD for United States Dollars. This currency is used for all amount fields in the order and line orders. Currency codes are listed in the Currencies [fx_currency] table.
order_line_items – List of objects that define each order line item in the order. Located in the Order Line Items [sn_csm_om_order_line_item] table. Required properties in each order line item object:
- account for B2B orders or consumer for B2C orders.
  - account – Sys_id of the business account assigned to this order line item. Located in the Accounts [customer_account] table.
  - consumer – Sys_id of the consumer assigned to this order line item. Located in the Consumers [csm_consumer] table.
- order_line_characteristics – List of objects defining associated order line characteristics. Order line characteristics are located in the Order Line Characteristics [sn_csm_om_order_characteristic_value] table.
- product_offering – Sys_id of the product listed in the Product Offerings [sn_prd_pm_product_offering] table.
- quantity – Number of product models ordered.
- unit_of_measurements – Sys_id for the ordered unit of measure listed in the Unit of Measures [sn_prd_pm_uom] table.

The Request body parameters table contains more details.