Teamwork Commerce Doc Hub > Developers > API Reference > Sales Order API Template

Sales Order API Template

Overview

You can use the POST Sales Order Import API to create Sales Orders in CHQ.

Method: POST
URI: CloudHQ URL/chqapi/import/sales-order

Parameters:

Accept: application/json
Content-Type: application/json
Authorization: ApiKey

Request Field Details

SalesOrders

Field Name Required Type Max Display Description

SalesOrderNo Y String 128 Y Internal identifier of sales order

Status N Enum Y Specifies the status of sales order. Enum values: InReview, Approved, Shipping, Completed, Cancelled

DeliveryMethod N Enum Y Specifies the delivery method of sales order. Enum values: Ship, StorePickUp

LocationID Y String Y An identifier or code of the location

SaleCreditLocationId Y String Y An identifier or code of the sales credit location

SellFromLocationId N String Y An identifier or code of the sell from location

LargeMemo N String No limit Y Any notes/comments for sales order

ShippingMethodId N String Y An identifier or code of the shipping method

SalesOrderInstruction

WebInstruction

Field Name Required Type Max Display Description

EcommerceChannelId Y String Y

WebOrderNo Y String 50 Y

ShipPartial Y Boolean Y

SendSaleInstruction

Field Name Required Type Max Display Description

ShipPartial Y Boolean Y

Field Name	Required	Type	Max	Display	Description
SalesOrderNo	Y	String	128	Y	Internal identifier of sales order
Status	N	Enum		Y	Specifies the status of sales order. Enum values: InReview, Approved, Shipping, Completed, Cancelled
DeliveryMethod	N	Enum		Y	Specifies the delivery method of sales order. Enum values: Ship, StorePickUp
LocationID	Y	String		Y	An identifier or code of the location
SaleCreditLocationId	Y	String		Y	An identifier or code of the sales credit location
SellFromLocationId	N	String		Y	An identifier or code of the sell from location
LargeMemo	N	String	No limit	Y	Any notes/comments for sales order
ShippingMethodId	N	String		Y	An identifier or code of the shipping method

Field Name	Required	Type	Max	Display
EcommerceChannelId	Y	String		Y
WebOrderNo	Y	String	50	Y
ShipPartial	Y	Boolean		Y

Field Name	Required	Type	Max	Display	Description
ShipPartial	Y	Boolean		Y

Customer

BillInfo

Field Name Required Type Max Display Description

LastName Y (if new customer) String 128 N Customer’s Last Name

FirstName Y (if new customer) String 128 N Customer’s First Name

Address1 Y (if new customer) String 128 N First line of customer’s address

Address2 Y (if new customer) String 128 N Second line of customer’s address

Address3 Y (if new customer) String 128 N Third line of customer’s address

Address4 Y (if new customer) String 128 N Fourth line of customer’s address

Address5 Y (if new customer) String 128 N Fifth line of customer’s address

City Y (if new customer) String 128 N Customer’s billing city

CountryCode Y (if new customer) String 128 N Customer’s billing country code

State Y (if new customer) String 128 N Customer’s billing state

PostalCode Y (if new customer) String 128 N Customer’s billing Postal code

Phone1 Y (if new customer) String 128 N Customer’s phone number

Email Y (if new customer) String 128 N Customer’s email address

Field Name	Required	Type	Max	Display	Description
LastName	Y (if new customer)	String	128	N	Customer’s Last Name
FirstName	Y (if new customer)	String	128	N	Customer’s First Name
Address1	Y (if new customer)	String	128	N	First line of customer’s address
Address2	Y (if new customer)	String	128	N	Second line of customer’s address
Address3	Y (if new customer)	String	128	N	Third line of customer’s address
Address4	Y (if new customer)	String	128	N	Fourth line of customer’s address
Address5	Y (if new customer)	String	128	N	Fifth line of customer’s address
City	Y (if new customer)	String	128	N	Customer’s billing city
CountryCode	Y (if new customer)	String	128	N	Customer’s billing country code
State	Y (if new customer)	String	128	N	Customer’s billing state
PostalCode	Y (if new customer)	String	128	N	Customer’s billing Postal code
Phone1	Y (if new customer)	String	128	N	Customer’s phone number
Email	Y (if new customer)	String	128	N	Customer’s email address

SellInfo

Field Name Required Type Max Display Description

LastName Y (if new customer) String 128 Y Customer’s Last Name

FirstName Y (if new customer) String 128 Y Customer’s First Name

Address1 Y (if new customer) String 128 Y First line of customer’s address

Address2 Y (if new customer) String 128 Y Second line of customer’s address

Address3 Y (if new customer) String 128 Y Third line of customer’s address

Address4 Y (if new customer) String 128 Y Fourth line of customer’s address

Address5 Y (if new customer) String 128 Y Fifth line of customer’s address

City Y (if new customer) String 128 Y Customer’s city

CountryCode Y (if new customer) String 128 Y Customer’s country code

State Y (if new customer) String 128 Y Customer’s state

PostalCode Y (if new customer) String 128 Y Customer’s postal code

Phone1 Y (if new customer) String 128 Y Customer’s phone number

Email Y (if new customer) String 128 Y Customer’s email address

Field Name	Required	Type	Max	Display	Description
LastName	Y (if new customer)	String	128	Y	Customer’s Last Name
FirstName	Y (if new customer)	String	128	Y	Customer’s First Name
Address1	Y (if new customer)	String	128	Y	First line of customer’s address
Address2	Y (if new customer)	String	128	Y	Second line of customer’s address
Address3	Y (if new customer)	String	128	Y	Third line of customer’s address
Address4	Y (if new customer)	String	128	Y	Fourth line of customer’s address
Address5	Y (if new customer)	String	128	Y	Fifth line of customer’s address
City	Y (if new customer)	String	128	Y	Customer’s city
CountryCode	Y (if new customer)	String	128	Y	Customer’s country code
State	Y (if new customer)	String	128	Y	Customer’s state
PostalCode	Y (if new customer)	String	128	Y	Customer’s postal code
Phone1	Y (if new customer)	String	128	Y	Customer’s phone number
Email	Y (if new customer)	String	128	Y	Customer’s email address

ShipInfo

Field Name Required Type Max Display Description

LastName Y (if new customers) String 128 Y Customer’s Last Name

FirstName Y (if new customers) String 128 Y Customer’s First Name

Address1 Y (if new customers) String 128 Y First line of customer’s address

Address2 Y (if new customers) String 128 Y Second line of customer’s address

Address3 Y (if new customers) String 128 Y Third line of customer’s address

Address4 Y (if new customers) String 128 Y Fourth line of customer’s address

Address5 Y (if new customers) String 128 Y Fifth line of customer’s address

City Y (if new customers) String 128 Y Customer’s ship to city

CountryCode Y (if new customers) String 128 Y Customer’s ship to country code

State Y (if new customers) String 128 Y Customer’s ship to state

PostalCode Y (if new customers) String 128 Y Customer’s ship to postal code

Phone1 Y (if new customers) String 128 Y Customer’s phone number

Email Y (if new customers) String 128 Y Customer’s email address

Field Name	Required	Type	Max	Display	Description
LastName	Y (if new customers)	String	128	Y	Customer’s Last Name
FirstName	Y (if new customers)	String	128	Y	Customer’s First Name
Address1	Y (if new customers)	String	128	Y	First line of customer’s address
Address2	Y (if new customers)	String	128	Y	Second line of customer’s address
Address3	Y (if new customers)	String	128	Y	Third line of customer’s address
Address4	Y (if new customers)	String	128	Y	Fourth line of customer’s address
Address5	Y (if new customers)	String	128	Y	Fifth line of customer’s address
City	Y (if new customers)	String	128	Y	Customer’s ship to city
CountryCode	Y (if new customers)	String	128	Y	Customer’s ship to country code
State	Y (if new customers)	String	128	Y	Customer’s ship to state
PostalCode	Y (if new customers)	String	128	Y	Customer’s ship to postal code
Phone1	Y (if new customers)	String	128	Y	Customer’s phone number
Email	Y (if new customers)	String	128	Y	Customer’s email address

Items

Field Name Required Type Max Display Description

SalesOrderItemId Y String Y An identifier or line number of the sales order item

ItemIdentifier Y String Y An identifier, external identifier, PLU, UPC or CLU of the inventory item

Status N Enum Y Specifies the status of sales order item

DeliveryMethod N String Y Specifies the delivery method of sales order item

SaleCreditLocationId N String Y An identifier or code of the sales credit location

SellFromLocationId N String Y An identifier or code of the sell from location

FulfillLocationId N String Y An identifier or code of the sell from location

ShippingMethodId N String Y An identifier or code of the shipping method

Qty Y Decimal Y The total quantity of items for the sales order

TotalAmount N Decimal Y The total amount for the sales order

TaxAmount N Decimal Y The total tax amount for the sales order

Field Name	Required	Type	Display	Description
SalesOrderItemId	Y	String	Y	An identifier or line number of the sales order item
ItemIdentifier	Y	String	Y	An identifier, external identifier, PLU, UPC or CLU of the inventory item
Status	N	Enum	Y	Specifies the status of sales order item
DeliveryMethod	N	String	Y	Specifies the delivery method of sales order item
SaleCreditLocationId	N	String	Y	An identifier or code of the sales credit location
SellFromLocationId	N	String	Y	An identifier or code of the sell from location
FulfillLocationId	N	String	Y	An identifier or code of the sell from location
ShippingMethodId	N	String	Y	An identifier or code of the shipping method
Qty	Y	Decimal	Y	The total quantity of items for the sales order
TotalAmount	N	Decimal	Y	The total amount for the sales order
TaxAmount	N	Decimal	Y	The total tax amount for the sales order

Payments

Field Name Required Type Max Display Description

PaymentMethodId Y String Y An identifier or code of the payment method

PaymentAmount N Decimal Y Amount of payment

ListOrder N Integer N Order of payment

Captured N Boolean N Specifies whether the payment is captured. ‘True’ if not specified

CardInfo

Field Name Required Type Max Display Description

AccountNumber N String 128 Y (Masked) The number of credit card account

CardExpMonth N Integer N The ordinal number of month when credit card expires

CardExpYear N Integer N The year when credit card expires

MerchantId N String n/a N The merchant identifier

CardOrderId N String 60 N The identifier of card order

ReferenceNum N String n/a N The reference number

TransactionId N String 30 N The identifier of payment transaction

CardType N Enum N The type of credit card. Enum values: Visa, Mastercard, Undefined

CardholderFirstName N String 128 N The first name of cardholder

CardholderLastName N String 128 N The last name of cardholder

CardholderAddress1 N String 128 N The first line of cardholder’s address

CardholderAddress2 N String 128 N The second line of cardholder’s address

CardholderCity N String 128 N The city of cardholder

CardholderState N String 128 N The state of cardholder

CardholderPostalCode N String 128 N Cardholder’s postal code

Field Name	Required	Type	Display	Description
PaymentMethodId	Y	String	Y	An identifier or code of the payment method
PaymentAmount	N	Decimal	Y	Amount of payment
ListOrder	N	Integer	N	Order of payment
Captured	N	Boolean	N	Specifies whether the payment is captured. ‘True’ if not specified

Field Name	Required	Type	Max	Display	Description
AccountNumber	N	String	128	Y (Masked)	The number of credit card account
CardExpMonth	N	Integer		N	The ordinal number of month when credit card expires
CardExpYear	N	Integer		N	The year when credit card expires
MerchantId	N	String	n/a	N	The merchant identifier
CardOrderId	N	String	60	N	The identifier of card order
ReferenceNum	N	String	n/a	N	The reference number
TransactionId	N	String	30	N	The identifier of payment transaction
CardType	N	Enum		N	The type of credit card. Enum values: Visa, Mastercard, Undefined
CardholderFirstName	N	String	128	N	The first name of cardholder
CardholderLastName	N	String	128	N	The last name of cardholder
CardholderAddress1	N	String	128	N	The first line of cardholder’s address
CardholderAddress2	N	String	128	N	The second line of cardholder’s address
CardholderCity	N	String	128	N	The city of cardholder
CardholderState	N	String	128	N	The state of cardholder
CardholderPostalCode	N	String	128	N	Cardholder’s postal code

JSON Request Example

Click to expand

{
    "Source": "string",
    "Data": {
        "Request": {
            "ImportSettings": {
                "ItemSetting": "CLU",
                "LocationSetting": "Code",
                "SalesOrderSetting": "SalesOrderNo",
                "SalesOrderItemSetting": "LineNo",
                "ShippingMethodSetting": "Code",
                "CustomerSetting": "Phone",
                "PaymentMethodSetting": "Code",
                "EcommerceChannelSetting": "Name",
                "ValidateState": "false"
            },
            "SalesOrders": [{
                "SalesOrderNo": "David Order",
                "Status": "Approved",
                "DeliveryMethod": "Ship",
                "LocationId": "WECHAT",
                "SaleCreditLocationId": "WECHAT",
                "SellFromLocationId": "CN-3PL",
                "LargeMemo": "",
                "CustomLookupValue4": "Wechat",
                "ShippingMethodId": "SFEXND-L1",
                "SalesOrderInstruction": {
                },
                "Customer": {
                    "GuestCheckout": "true",
                    "CustomerId": "18616744577",
                    "BillInfo": {
                        "LastName": "O",
                        "FirstName": "David",
                        "Email": "TEST1@gmail.com",
                        "Address1": "test street 1",
                        "City": "London",
                        "CountryCode": "US",
                        "State": "London",
                        "PostalCode": "123123",
                        "Phone1": "123123123"
                    },
                    "SellInfo": {
                        "LastName": "O",
                        "FirstName": "David",
                        "Email": "TEST1@gmail.com",
                        "Address1": "test street 1",
                        "City": "London",
                        "CountryCode": "US",
                        "State": "London",
                        "PostalCode": "123123",
                        "Phone1": "123123123"
                    },
                    "ShipInfo": {
                        "LastName": "o",
                        "FirstName": "David",
                        "Email": "TEST1@gmail.com",
                        "Address1": "test street 1",
                        "City": "London",
                        "CountryCode": "US",
                        "State": "London",
                        "PostalCode": "123123",
                        "Phone1": "123123123"
                    }
                },
                "Items": [{
                    "SalesOrderItemId": "1",
                    "ItemIdentifier": "2HL173-900105",
                    "Status": "InReview",
                    "DeliveryMethod": "Ship",
                    "SaleCreditLocationId": "WECHAT",
                    "SellFromLocationId": "WECHAT",
                    "FulfillLocationId": "CN-3PL",
                    "ShippingMethodId": "SFEXND-L1",
                    "Qty": 1,
                    "TotalAmount": 1800.0,
                    "TaxAmount": 207.0792
                }, {
                    "SalesOrderItemId": "2",
                    "ItemIdentifier": "2HL173-900105",
                    "Status": "InReview",
                    "DeliveryMethod": "Ship",
                    "SaleCreditLocationId": "WECHAT",
                    "SellFromLocationId": "WECHAT",
                    "FulfillLocationId": "CN-3PL",
                    "ShippingMethodId": "SFEXND-L1",
                    "Qty": 1,
                    "TotalAmount": 1800.0,
                    "TaxAmount": 207.0792
                }, {
                    "SalesOrderItemId": "3",
                    "ItemIdentifier": "2HL173-900105",
                    "Status": "InReview",
                    "DeliveryMethod": "Ship",
                    "SaleCreditLocationId": "WECHAT",
                    "SellFromLocationId": "WECHAT",
                    "FulfillLocationId": "CN-3PL",
                    "ShippingMethodId": "SFEXND-L1",
                    "Qty": 1,
                    "TotalAmount": 1800.0,
                    "TaxAmount": 207.0792
                }, {
                    "SalesOrderItemId": "4",
                    "ItemIdentifier": "25E173-900103",
                    "Status": "InReview",
                    "DeliveryMethod": "Ship",
                    "SaleCreditLocationId": "WECHAT",
                    "SellFromLocationId": "WECHAT",
                    "FulfillLocationId": "CN-3PL",
                    "ShippingMethodId": "SFEXND-L1",
                    "Qty": 1,
                    "TotalAmount": 1000.0,
                    "TaxAmount": 115.044
                }, {
                    "SalesOrderItemId": "5",
                    "ItemIdentifier": "25E173-900103",
                    "Status": "InReview",
                    "DeliveryMethod": "Ship",
                    "SaleCreditLocationId": "WECHAT",
                    "SellFromLocationId": "WECHAT",
                    "FulfillLocationId": "CN-3PL",
                    "ShippingMethodId": "SFEXND-L1",
                    "Qty": 1,
                    "TotalAmount": 1000.0,
                    "TaxAmount": 115.044
                }, {
                    "SalesOrderItemId": "6",
                    "ItemIdentifier": "25E173-900103",
                    "Status": "InReview",
                    "DeliveryMethod": "Ship",
                    "SaleCreditLocationId": "WECHAT",
                    "SellFromLocationId": "WECHAT",
                    "FulfillLocationId": "CN-3PL",
                    "ShippingMethodId": "SFEXND-L1",
                    "Qty": 1,
                    "TotalAmount": 1000.0,
                    "TaxAmount": 115.044
                }],
                "Payments": [{
                    "PaymentMethodId": "wechat",
                    "PaymentAmount": 8400.0,
                    "ListOrder": 0,
                    "Captured": "true",
                    "CardInfo": {
                        "AccountNumber": "0",
                        "CardExpMonth": "0",
                        "CardExpYear": "0",
                        "MerchantId": "manual",
                        "CardOrderId": null,
                        "ReferenceNum": null,
                        "TransactionId": "4200000729202011308853551958",
                        "CardType": "Undefined",
                        "CardholderFirstName": null,
                        "CardholderLastName": null,
                        "CardholderAddress1": null,
                        "CardholderAddress2": null,
                        "CardholderCity": null,
                        "CardholderState": null,
                        "CardholderCountryCode": null,
                        "CardholderPostalCode": null
                    }
                }]
            }]
        }
    }
}

Response Field Details

Field Name Type

Id String

Status String

Progress String

TotalRecords Integer

AcceptedRecords Integer

ErrorRecords Integer

ElapsedTime Date

ErrorMessage String

Lines

Field Name Type

EntityNo Integer

EntityId String

Error String

Status String

ApiType String

Source String

Field Name	Type
Id	String
Status	String
Progress	String
TotalRecords	Integer
AcceptedRecords	Integer
ErrorRecords	Integer
ElapsedTime	Date
ErrorMessage	String

Field Name	Type
EntityNo	Integer
EntityId	String
Error	String
Status	String
ApiType	String
Source	String

JSON Response Example

Click to expand


{
    "Id": "e9ea45ba-3816-4773-920c-d66c105d5141",
    "Status": "InProcess",
    "Progress": null,
    "TotalRecords": null,
    "AcceptedRecords": null,
    "ErrorRecords": null,
    "ElapsedTime": null,
    "ErrorMessage": null,
    "Lines": [
        {
            "EntityNo": "789",
            "EntityId": "22dbe14a-a5ca-45c3-b8c5-c9aaf44e2011",
            "Error": null,
            "Status": "InProcess"
        }
    ],
    "ApiType": "simplified-sales-order-import",
    "Source": "string",
    "Response": null
}

Sales Order Import API Best Practices

Sales Order Import API endpoint can be used to update/change the status of an order. Commonly used to cancel orders
Good to have email and phone if email automation is required in the future
In the SalesOrderInstruction header use WebOrderInstruction for any ecommerce orders. If the sales order does not stem from ecommerce use SendSaleInstruction node
Any location related parameter will need to be setup on CHQ first or the import of the sales order will fail
After calling the Sales Order Import API, the http response will be in the InProcess status. To verify if an order has been successfully posted to CHQ you can use the /chqapi/status endpoint to verify.
For the qty parameter in the Items header please use 1 as the maximum value, this will ensure that a unique RMA code per line will be generated. Please contact your integrations specialist to discuss.