REST API reference › API reference › API implementation and reference

Release: Australia · Updated: 2026-03-12 · Official documentation · View source

Order API

The Order API provides endpoints for retrieving and creating orders with order line items for the Customer Service Management application.

This API requires the Order Management (app-csm-order-mgmt) store application and is provided within the sn_ind_tmt_orm namespace. For information, see Sales Customer Relationship 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.

Parent Topic:REST API reference

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}

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request 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.Data type: String Table: Orders \[sn\_csm\_om\_order\]

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

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.

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. For a list of possible status codes used in the REST API, see REST API HTTP response 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 consumer record. Identifies the consumer for B2C orders.Data type: String
contact	Sys\_id of the customer contact related to the account.Data type: String Table: Contacts \[customer\_contact\]
contract	Sys\_id of the Customer Service contract record.Data type: String Table: Contracts \[ast\_contract\]
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.Data type: String Table: Orders \[sn\_csm\_om\_order\]
order\_line\_items	Required. List of objects that define each order line item in the order. 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" } ] Table: Order Line Items [sn_csm_om_order_line_item]
order\_line\_items	List of objects that define each order line item in the order. Data type: Array of Objects "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 record.Data type: String Table: Locations \[cmn\_location\]
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. Data type: Array of Objects `"order_line_characteristics": [ { "characteristic": "String", "characteristic_option": "String" } ]`
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 .Data type: String Table: Order Line Characteristics \[sn\_csm\_om\_order\_characteristic\_value\]
order\_line\_items. order\_line\_characteristics. order\_line\_item	Sys\_id of this characteristic's order line item.Data type: String Table: Order Line Items \[sn\_csm\_om\_order\_line\_item\]
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 recordData type: String Table: Order Line Characteristics \[sn\_csm\_om\_order\_characteristic\_value\]
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	Sys\_id of the product model for the product listed prior to this item in the order line.Data type: String Table: Product Models \[cmdb\_model\]
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 productData type: String Table: Product Models \[cmdb\_model\]
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 record.Data type: String Table: Sold Products \[sn\_install\_base\_sold\_product\]
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: - failure - success 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 recordData type: String Table: Order Line Items \[sn\_csm\_om\_order\_line\_item\]
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.Data type: String Table: Currency Instances \[fx\_currency\_instance\]
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 record for an account.Data type: String Table: Accounts \[customer\_account\]
partner\_contact	For B2B orders, sys\_id of the primary contact of the partner for the partner account.Data type: String Table: Contacts \[customer\_contact\]
payment\_ref\_id	Unique identifier of the payment. For example, check number.Data type: String
price\_list	Sys_id of the associated price list record. 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 Table: Price Lists [sn_csm_pricing_price_list]
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 record.Data type: String Table: Locations \[cmn\_location\]
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 record.Data type: String Table: Orders \[sn\_csm\_om\_order\]
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 consumer record.
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. 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.