API Documentation

In-depth reference documentation for iQmetrix API's.

NAV

OVERVIEW

Note: To use the Sales Order API, you must be running RQ 6.7 or later.

The Sales Order API takes transaction information from a third-party system (for example, an online ecommerce solution) and submits it as a sales order to the RQ database. A sales order can be POSTed to:

The Sales Order API can return HAL in JSON responses to requests. Enable HAL in responses by including the Accept: application/hal+json. Omit HAL in responses by including Accept: application/json. By default (that is, if the Accept: header is not included), HAL is returned.

Both the /SaleOrder and /SaleInvoice endpoints process requests asynchronously, responding with 202 (Accepted) responses. The HTTP 202 response indicates only that the service recognizes the request format and that basic validations succeed. A 202 response does not imply success importing into RQ nor does it guarantee processing will complete successfully.

Note that the Sales Order Service depends on synchronization with the Customer Relationship Management (CRM) Service, and CRM synchronization must be enabled in RQ for the workflow to succeed; otherwise, RQ is not aware of the CRM customer created and assigned to the sales order. Similarly, if there are issues with CRM synchronization, RQ will not be aware of the CRM customer associated with the sales order. In this case, the sales order will be created and the system will send a success status code along with the identifier of the sales order; however, the sales order will not appear in RQ.

BASE URLS

Sandbox: https://salesorderdemo.iqmetrix.net/v1
Production: https://salesorder.iqmetrix.net/v1

RESOURCES

DiscountLineItem

{
    "LineNumber": 1,
    "Amount": 2.99,
    "Name": "BOGO 50",
    "DiscountCode": "M5512323DD1",
    "AssociatedLineItems": [
        1
    ],
    "RetailerCatalogId": "a183f1a9-c58f-426a-930a-9a6357db52ed"
}
Name Description
LineNumber (Integer) The line number of the discount item. An incrementable integer greater than one. Must be unique within the list of discount items.
Amount (Decimal) The amount the item has been discounted.
Name (String) The name of the discount being applied.
DiscountCode (String) The code for the discount being applied.
AssociatedLineItems (Array[Integer]) The LineItem number(s), if any, of the sales order item(s) being discounted using this discount.
RetailerCatalogId (GUID) The identifier of the CatalogItem in the retailer’s catalog.

Payment

{
    "Id": "c3c6647b-04b6-e5d9-1a89-1c1a367985b9",
    "AuthCode": "CMC623",
    "TransactionNumber": "CE507EA008F65516",
    "Token": "685576",
    "Amount": 0,
    "PaymentMethodId": "3500899b-22bb-426d-b642-1c0d6552d0ab",
    "CorrelationId": "TN15123X"
}
Name Description
Id (GUID) The identifier of the payment. The system generates this identifier when the payment object is created and returns it in the response to the POST request.
AuthCode (String) The authorization code for the payment. Maximum 1024 characters. This property is not used internally, but is available for your own business processes.
TransactionNumber (String) The transaction number of the payment. Maximum 1024 characters. This property is not used internally, but is available for your own business processes.
Token (String) A token associated with the payment. This property is not used internally, but is available for your own business processes.
Amount (Decimal) The amount of the payment.
PaymentMethodId (GUID) The identifier for the payment method in the iQmetrix Payments service. Read-only; set automatically.
CorrelationId (String) An identifier that can be used to correlate the payment to a payment in an external system. Although the Sales Order Service retains the full string, the string is trimmed to 30 characters when submitted to RQ.

SaleOrder

{
    "Id": "d8daa9df-0e3d-4355-b3f8-451b281b3be5",
    "DateCreatedUtc": "2018-01-04T16:00:00",
    "DateInsertedUtc": "0001-01-01T00:00:00",
    "DateUpdatedUtc": "0001-01-01T00:00:00",
    "CompanyId": 14146,
    "LocationId": 14192,
    "CustomerId": "a61ebc5a-b85f-66a3-dec3-260637dd796c",
    "Items": [
        {
            "LineNumber": 1,
            "ItemType": "InStock",
            "Quantity": 1,
            "ProductCatalogId": "55c8b270-63b9-a095-d975-9a730b3dacb4",
            "CorrelationId": "6716053127",
            "Price": 99.98,
            "PricingTermId": 2,
            "TaxLineItems": [
            {
                "TaxName": "Sales Tax",
                "TaxableAmount": 17.99,
                "Rate": 0.0125,
                "Tax": 0.22,
                "IqTaxServiceId": "fe73a2fd-1751-42a9-ac3d-d9d10e1317a4"
            }
          ]
        }
    ],
        "Payments": [
            {
                "Id": "3a296e6e-458f-47dc-9b45-a9cd63c52526",
                "AuthCode": "TXS-9138",
                "TransactionNumber": "48332093",
                "Token": "OslkhrXM",
                "Amount": 18.71,
                "PaymentMethodId": "3500899b-22bb-426d-b642-1c0d6552d0ab",
                "CorrelationId": "868XZDFN"
            }
        ],
    "TaxCalculationResultId": "e4b25c1b-876a-4c13-b562-c3ba1ac33a76",
    "BillingAddressId": "1e93b1bc-ecf7-46f5-8be4-e20284e0df36",
    "ShippingAddressId": "8f49e60a-5714-4fd2-9d68-223114227011",
    "PrintableId": "229045",
    "DropshipOrderId": "9dd08bfc-24a0-99ed-64c4-8b5602402f91",
    "UserId": 4349,
    "ShippingLineItems": [
        {
            "LineNumber": 1,
            "Type": "USPS",
            "Amount": 9.99,
            "CorrelationId": "6716053127",
            "RetailerCatalogId": "a183f1a9-c58f-426a-930a-9a6357db52ed",
            "AssociatedLineItems": [
                1
            ]
        }
    ],
    "DiscountLineItems": [
        {
            "LineNumber": 1,
            "Amount": 2.99,
            "Name": "BOGO 50",
            "DiscountCode": "M5512323DD1",
            "AssociatedLineItems": [
                1
            ],
            "RetailerCatalogId": "a183f1a9-c58f-426a-930a-9a6357db52ed"
        }
    ]
}
Name Description
Id (GUID) The identifier of the sales order. The system generates this identifier when the sales order is created and returns it in the response to the POST request.
DateCreatedUtc (DateTime) An ISO 8601 timestamp indicating when the sales order was created. Read-only. Filterable.
DateInsertedUtc (DateTime) An ISO 8601 timestamp indicating when the sales order was first posted to the Sales Order service. Read-only. Filterable.
DateUpdatedUtc (DateTime) An ISO 8601 timestamp indicating when the sales order was last updated. Read-only. Filterable.
CompanyId (Integer) The identifier of the company generating the sales order. Filterable.
LocationId (Integer) The identifier of the location generating the sales order. Filterable.
CustomerId (GUID) The identifier of the customer making the purchase. Filterable.
ExpiryDateUtc (String) An ISO 8601 UTC timestamp indicating when the sales order should expire. Filterable. The expiration of this date does not trigger any event in RQ; instead, this property can be used with your own business processes to determine when to expire sales orders.
Items (Array[SaleOrderItem]) An array of objects representing the items in the sales order.
Payments (Array[Payment]) An array of objects representing any payments made on the order.
TaxCalculationResultId (GUID) The identifier of a tax calculation returned by the IQ Tax Service.
BillingAddressId (GUID) The identifier of a customer billing address record. Currently, this address is not validated.
ShippingAddressId (GUID) The identifier of a customer shipping address record. Currently, the address is not validated.
PrintableId (String) An identifier from the external system that can be used to reference the order; for example, the online order confirmation number. This identifier is mentioned in the comments section of the RQ sales order and the invoices. Filterable. Maximum 50 characters.
DropshipOrderId (GUID) When the item type is Dropship, either DropshipOrderId or SupplierEntityId must be provided. Forbidden otherwise. The identifier for this order in the Order service. Filterable.
UserId (Integer) Identifier of a valid user in RQ. This user must have sufficient permissions to create sales orders, add products, and create invoices at this location. Filterable.
ShippingLineItems (Array[ShippingLineItem]) A list of shipping line items associated with all or parts of this sales order.
DiscountLineItems (Array[DiscountLineItem]) A list of discount line items associated with all or parts of this sales order.

SaleOrderItem

{
    "LineNumber": 1,
    "ProductCatalogId": "55c8b270-63b9-a095-d975-9a730b3dacb4",
    "Quantity": 1,
    "Price": 99.98,
    "PricingTermId": 2,
    "CorrelationId": "6716053127",
    "ItemType": "InStock",
    "SupplierEntityId": null,
    "SerialNumber": null,
    "TaxLineItems": [
        {
            "TaxName": "Sales Tax",
            "TaxableAmount": 99.98,
            "Rate": 0.05,
            "Tax": 4.99,
            "IqmetrixTaxServiceId": "437ccff6-09c6-4356-8190-7ca1e999fefb"
        }
    ]
}
Name Description
LineNumber (Integer) The line number of the item. An incrementable integer greater than one. Must be unique within the list of items.
ProductCatalogId (GUID) The identifier of the item in the iQmetrix Product Library.
Quantity (Integer) The number of items of this type in the order.
Price (Decimal) The price of the item.
PricingTermId (Integer) The identifier of a pricing term record.
CorrelationId (String) An identifier that can be used to correlate the item to an identifier in an external system. Although the Sales Order Service retains the full string, the string is trimmed to 30 characters when submitted to RQ.
ItemType (String) The item type. Supported values are InStock (the item is in stock) or Dropship (the item is to be drop-shipped).
SupplierEntityId (Integer) Applies to Dropship item types only. The identifier of the supplier associated with the product.
SerialNumber (String) The serial number for a serialized product where the quantity is 1 or -1.
TaxLineItems (Array[TaxLineItem]) A list of taxes associated with all or parts of this sales order item.

SaleOrderStatusLog

{
    "UpdatedBy": "Sam Smith",
    "Status": "Success",
    "Details": "Sent to POS",
    "Id": "3ff6e55b-1753-4c27-8b8e-3befa73b13c8",
    "UpdatedDate": "2017-07-17 10:35",
    "SaleOrderId": "addbcea6-5f28-0c0a-027a-6fbc6b768f71",
    "UserId": 4332
}
Name Description
UpdatedBy (String) The user or service associated with the operation. Filterable.
Status (String) The status of the operation. Status can be Success or Failure. Filterable.
Details (String) Further details about operation. Filterable.
Id (GUID) The identifier of the log entry. The system generates this identifier when the log entry is created and returns it when a Status Log is retrieved. Filterable.
UpdatedDate (DateTime) An ISO 8601 UTC timestamp indicating when the log entry was created. Filterable.
SaleOrderId (GUID) The identifier of the sale order associated with the operation.
UserId (Integer) The identifier of the user associated with the log entry. Filterable.

ShippingLineItem

{
    "LineNumber": 1,
    "Type": "USPS",
    "Amount": 9.99,
    "CorrelationId": "6716053127",
    "AssociatedLineItems": [
        1
    ],
    "RetailerCatalogId": "a183f1a9-c58f-426a-930a-9a6357db52ed"
}
Name Description
LineNumber (Integer) The line number of the shipping item. An incrementable integer greater than one. Must be unique within the list of shipping items.
Type (String) The shipping type.
Amount (Decimal) The shipping amount.
CorrelationId (String) An identifier that can be used to correlate this shipping information with shipping information in another system.
RetailerCatalogId (GUID) The identifier of the item in the retailer’s catalog.
AssociatedLineItems (Array[integer]) The LineItem number(s) of the sales order item(s) being shipped using this shipping line item.

TaxDetail

The TaxDetail resource returns information from the iQmetrix tax service.

{
    "TaxId": "321",
    "CountryCode": "CA",
    "RegionCode": "AB",
    "TaxType": "Sales Tax",
    "TaxAuthority": "IRS",
    "TaxAuthorityType": "Internal Revenue Service",
    "Rate": 4,
    "Tax": 9,
    "Taxable": 2,
    "UnitTax": 1,
    "TaxName": "Sales Tax",
    "EffectiveZoneLevel": "Atlanta"
}
Name Description
TaxId (String) The identifier of the tax rate in the source system.
CountryCode (String) The ISO 3166-1 alpha-2 standard code for the country.
RegionCode (String) The ISO 3166-2 standard code for the state or province.
TaxType (String) The type of tax being applied.
TaxAuthority (String) The tax authority to report the tax to.
TaxAuthorityType (String) The description of the tax authority.
Rate (Decimal) The effective tax rate for the tax jurisdiction.
Tax (Decimal) The amount of tax payable to the tax jurisdiction.
Taxable (Decimal) The taxable amount on the line.
UnitTax (Decimal) The tax amount per unit for this detail.
TaxName (String) The description of the tax being applied.
EffectiveZoneLevel (String) The effective tax zone level of the tax.

TaxLineItem

A tax line item which corresponds to a line item on the sales order. Either full tax information is provided (all of TaxName, TaxableAmount, Rate, and Tax) or a reference to a tax query in the iQmetrix tax service (IqTaxServiceId), but not both.

{
    "TaxName": "Sales Tax",
    "TaxableAmount": 100,
    "Rate": 1,
    "Tax": 1,
    "IqTaxServiceId": "d561459b-7ae2-42ed-8951-afe88313477c"
}
Name Description
TaxName (String) The name of the tax being applied.
TaxableAmount (Decimal) The taxable amount.
Rate (Decimal) The effective tax rate.
Tax (Decimal) The amount of tax charged.
IqTaxServiceId (GUID) The identifier of a tax query in the iQmetrix tax service.

REQUESTS

POST a Sales Order and Create an Invoice in RQ

A POST request to the /SaleInvoice endpoint submits the order to RQ and automatically creates the associated invoice.

The sales order in RQ is converted to an invoice in RQ in two stages:

The staging invoice has its own ID, which is returned when the sales order is submitted. If payment fails or is interrupted, or if there is an interruption in RQ service, you can recover the invoice information in RQ by searching on the staging invoice ID.

When the tender invoice is created, a link to it is provided in RQ so that you can open the invoice.

Request

POST /Companies({CompanyId})/SaleInvoice

Example Request

POST /Companies(14146)/SaleInvoice
Authorization: Bearer U3NkZsa-ZGZTRWRmU3JkZlNyBwsmGBFUJBkTUSc
Accept: application/json
Content-Type: application/json

{
    "DateCreatedUtc": "2018-01-04T16:00:00",
    "LocationId": 14192,
    "CustomerId": "a61ebc5a-b85f-66a3-dec3-260637dd796c",
    "Items": [
        {
            "LineNumber": 1,
            "ItemType": "InStock",
            "Quantity": 1,
            "ProductCatalogId": "55c8b270-63b9-a095-d975-9a730b3dacb4",
            "CorrelationId": "6716053127",
            "Price": 99.98,
            "PricingTermId": 2,
            "TaxLineItems": [
            {
                "IqTaxServiceId" : "fe73a2fd-1751-42a9-ac3d-d9d10e1317a4"
            },
                ]
        }
    ],
    "Payments": [
        {
            "Id": "e4b25c1b-876a-4c13-b562-c3ba1ac33a76",
            "Amount" : 100.20,
            "AuthCode": "VISA_253189",
            "TransactionNumber": "DSX-39718",
            "Token": "OslkhrXM",
            "PaymentMethodId": "3500899B-22BB-426D-B642-1C0D6552D0AB",
            "CorrelationId" : "DSX-87924"
        }
    ],
   "DiscountLineItems" : [
           {
               "LineNumber": 1,
               "Amount" : 9,
               "Name" : "BOGO 50",
               "DiscountCode" : "BOGO50",
               "AssociatedLineItems" : [1]
           }
    ],
    "TaxCalculationResultId": "e4b25c1b-876a-4c13-b562-c3ba1ac33a76",
    "BillingAddressId": "1e93b1bc-ecf7-46f5-8be4-e20284e0df36",
    "ShippingAddressId": "8f49e60a-5714-4fd2-9d68-223114227011",
    "PrintableId": "229045",
    "DropshipOrderId": "77797903-46B4-4D33-BCDD-1D0348515F39",
    "UserId": 4349
}

Path Parameters

Name Description
CompanyId (Integer) The identifier of the company generating the sales order.

Request Parameters

SaleOrder

Name Description
DateCreatedUtc (DateTime) Required. An ISO 8601 UTC timestamp indicating when the sales order was created.
CompanyId (Integer) Required. The identifier of the company generating the sales order. Filterable.
LocationId (Integer) Required. The identifier of the location generating the sales order. Filterable.
CustomerId (GUID) Required. The identifier of the customer making the purchase. Filterable.
ExpiryDateUtc (String) Optional. An ISO 8601 UTC timestamp indicating when the sales order should expire. Filterable. The expiration of this date does not trigger any event in RQ; instead, this property can be used with your own business processes to determine when to expire sales orders.
Items (Array[SaleOrderItem]) An array of objects representing the items in the sales order.
Payments (Array[Payment]) An array of objects representing any payments made on the order.
TaxCalculationResultId (GUID) Optional. The identifier of a tax calculation returned by the IQ Tax Service.
BillingAddressId (GUID) Optional. The identifier of a customer billing address record. Currently, this address is not validated.
ShippingAddressId (GUID) Optional. The identifier of a customer shipping address record. Currently, the address is not validated.
PrintableId (String) Required. An identifier from the external system that can be used to reference the order; for example, the online order confirmation number. This identifier is mentioned in the comments section of the RQ sales order and the invoices. Filterable. Maximum 50 characters.
DropshipOrderId (GUID) When the item type is Dropship, either DropshipOrderId or SupplierEntityId must be provided; forbidden otherwise. The identifier for this order in the Order service. Filterable.
UserId (Integer) Optional. Identifier of a valid user in RQ. This user must have sufficient permissions to create sales orders, add products, and create invoices at this location. Filterable.
ShippingLineItems (Array[ShippingLineItem]) Optional. A list of shipping line items associated with all or parts of this sales order.
DiscountLineItems (Array[DiscountLineItem]) Optional. A list of discount line items associated with all or parts of this sales order.

SaleOrderItem

Name Description
LineNumber (Integer) Required. The line number of the item. An incrementable integer greater than one. Must be unique within the list of items.
ProductCatalogId (GUID) Required. The identifier of the item in the iQmetrix Product Library.
Quantity (Integer) Required. The number of items of this type in the order.
Price (Decimal) Required. The price of the item.
PricingTermId (Integer) Optional. The identifier of a pricing term record.
CorrelationId (String) Optional. An identifier that can be used to correlate the item to an identifier in an external system. Although the Sales Order Service retains the full string, the string is trimmed to 30 characters when submitted to RQ.
ItemType (String) Required. The item type. Supported values are InStock (the item is in stock) or Dropship (the item is to be drop-shipped). When the item type is Dropship, either DropshipOrderId or SupplierEntityId must be provided.
SupplierEntityId (Integer) Required for Dropship item types; forbidden otherwise. The identifier of the supplier associated with the product.
SerialNumber (String) The serial number for a serialized product where the quantity is 1 or -1.
TaxLineItems (Array[TaxLineItem]) A list of taxes associated with all or parts of this sales order item.

TaxLineItems

Either all of TaxName, TaxableAmount, Rate, and Tax must be supplied, or else just IqmetrixTaxServiceId, but not both.

Name Description
TaxName (String) Required if IqmetrixTaxServiceId is not specified, forbidden otherwise. The name of the tax being applied.
TaxableAmount (Decimal) Required if IqmetrixTaxServiceId is not specified, forbidden otherwise.The taxable amount.
Rate (Decimal) Required if IqmetrixTaxServiceId is not specified, forbidden otherwise. The effective tax rate.
Tax (Decimal) Required if IqmetrixTaxServiceId is not specified, forbidden otherwise. The amount of tax charged.
IqmetrixTaxServiceId (GUID) Required if TaxName, TaxableAmount, Rate, and Tax are specified, forbidden if they are. The identifier of a tax query in the iQmetrix tax service.

Payments

The array is required, but can be empty if there are no payments.

Name Description
AuthCode (String) Optional. The authorization code for the payment.
TransactionNumber (String) Optional. The transaction number of the payment.
Token (String) Optional. The token associated with the payment.
Amount (Decimal) - Optional. The amount of the payment.  
CorrelationId (String) Optional. Correlates this payment with a payment record in another system. Although the Sales Order Service retains the full string, the string is trimmed to 30 characters when submitted to RQ.

Response

Example Response

HTTP 202 Content-Type: application/json
{
    "Id": "d8daa9df-0e3d-4355-b3f8-451b281b3be5",
    "DateCreatedUtc": "2018-01-04T16:00:00",
    "DateInsertedUtc": "0001-01-01T00:00:00",
    "DateUpdatedUtc": "0001-01-01T00:00:00",
    "CompanyId": 14146,
    "LocationId": 14192,
    "CustomerId": "a61ebc5a-b85f-66a3-dec3-260637dd796c",
    "ExpiryDateUtc": null,
    "Items": [
        {
            "LineNumber": 1,
            "ProductCatalogId": "55c8b270-63b9-a095-d975-9a730b3dacb4",
            "Quantity": 1,
            "Price": 99.98,
            "PricingTermId": 2,
            "CorrelationId": "6716053127",
            "ItemType": "InStock",
            "SupplierEntityId": null,
            "SerialNumber": null,
            "TaxLineItems": [
                {
                    "IqTaxServiceId": "fe73a2fd-1751-42a9-ac3d-d9d10e1317a4"
                }
            ]
        }
    ],
    "Payments": [
        {
            "Id": "e4b25c1b-876a-4c13-b562-c3ba1ac33a76",
            "Amount" : 100.20,
            "AuthCode": "VISA_253189",
            "TransactionNumber": "DSX-39718",
            "Token": "OslkhrXM",
            "PaymentMethodId": "3500899B-22BB-426D-B642-1C0D6552D0AB",
            "CorrelationId" : "DSX-87924"
        }
    ],
    "TaxCalculationResultId": "e4b25c1b-876a-4c13-b562-c3ba1ac33a76",
    "BillingAddressId": "1e93b1bc-ecf7-46f5-8be4-e20284e0df36",
    "ShippingAddressId": "8f49e60a-5714-4fd2-9d68-223114227011",
    "PrintableId": "229045",
    "DropshipOrderId": "9dd08bfc-24a0-99ed-64c4-8b5602402f91",
    "UserId": 4349,
    "ShippingLineItems": [
        {
            "LineNumber": 1,
            "Type": "USPS",
            "Amount": 9.99,
            "CorrelationId": "6716053127",
            "RetailerCatalogId": "a183f1a9-c58f-426a-930a-9a6357db52ed",
            "AssociatedLineItems": [
                1
            ]
        }
    ],
    "DiscountLineItems": [
        {
            "LineNumber": 1,
            "Amount": 2.99,
            "Name": "BOGO 50",
            "DiscountCode": "M5512323DD1",
            "AssociatedLineItems": [
                1
            ],
            "RetailerCatalogId": "a183f1a9-c58f-426a-930a-9a6357db52ed"
        }
    ]
}

A successful request returns a 202 (Accepted) response code with the completed object in the body of the response, including the generated identifier. For a description of parameters defined for the SaleOrder resource, see SaleOrder.

POST a Sales Order with No Invoice

A POST request to the /SaleOrder endpoint submits the request to RQ but does not automatically create the invoice. The invoice must be created manually subsequently.

Request

POST /Companies({CompanyId})/SaleOrder

Example Request

POST /Companies(14146)/SaleOrder
Authorization: Bearer U3NkZsa-ZGZTRWRmU3JkZlNyBwsmGBFUJBkTUSc
Accept: application/json
Content-Type: application/json

{
    "DateCreatedUtc": "2018-01-04T16:00:00",
    "LocationId": 14192,
    "CustomerId": "a61ebc5a-b85f-66a3-dec3-260637dd796c",
    "Items": [
        {
            "LineNumber": 1,
            "ProductCatalogId": "55c8b270-63b9-a095-d975-9a730b3dacb4",
            "Quantity": 1,
            "Price": 99.98,
            "PricingTermId": 2,
            "CorrelationId": "6716053127",
            "ItemType": "InStock",
            "SupplierEntityId": null,
            "SerialNumber": null,
            "TaxLineItems": [
                {
                    "TaxName": "Sales Tax",
                    "TaxableAmount": 17.99,
                    "Rate": 0.0125,
                    "Tax": 0.22
                }
            ]
        }
    ],
    "Payments": [
        {
            "Id": "e4b25c1b-876a-4c13-b562-c3ba1ac33a76",
            "Amount" : 100.20,
            "AuthCode": "VISA_253189",
            "TransactionNumber": "DSX-39718",
            "Token": "OslkhrXM",
            "PaymentMethodId": "3500899B-22BB-426D-B642-1C0D6552D0AB",
            "CorrelationId" : "DSX-87924"
        }
    ],
    "TaxCalculationResultId": "e4b25c1b-876a-4c13-b562-c3ba1ac33a76",
    "BillingAddressId": "1e93b1bc-ecf7-46f5-8be4-e20284e0df36",
    "ShippingAddressId": "8f49e60a-5714-4fd2-9d68-223114227011",
    "PrintableId": "229045",
    "DropshipOrderId": "77797903-46B4-4D33-BCDD-1D0348515F39",
    "ShippingLineItems": [
        {
            "LineNumber": 1,
            "Type": "USPS",
            "Amount": 9.99,
            "CorrelationId": "6716053127",
            "AssociatedLineItems": [
                1
            ],
            "RetailerCatalogId": "a183f1a9-c58f-426a-930a-9a6357db52ed"
        }
    ],
    "DiscountLineItems": [
        {
            "LineNumber": 1,
            "Amount": 2.99,
            "Name": "BOGO 50",
            "DiscountCode": "M5512323DD1",
            "AssociatedLineItems": [
                1
            ],
            "RetailerCatalogId": "a183f1a9-c58f-426a-930a-9a6357db52ed"
        }
    ],
    "PrintableId": "5612341",
    "DropshipOrderId": "9dd08bfc-24a0-99ed-64c4-8b5602402f91",
    "TaxCalculationResultId": "706fd935-f1b4-4f19-153d-e3f910d5b83e"
}

Path Parameters

Name Description
CompanyId (Integer) Required. The identifier of the company generating the sales order.

Request Parameters

SaleOrder

Name Description
DateCreatedUtc (DateTime) Required. An ISO 8601 UTC timestamp indicating when the sales order was created.
CompanyId (Integer) Required. The identifier of the company generating the sales order. Filterable.
LocationId (Integer) Required. The identifier of the location generating the sales order. Filterable.
CustomerId (GUID) Required. The identifier of the customer making the purchase. Filterable.
ExpiryDateUtc (String) Optional. An ISO 8601 UTC timestamp indicating when the sales order should expire. Filterable. The expiration of this date does not trigger any event in RQ; instead, this property can be used with your own business processes to determine when to expire sales orders.
Items (Array[SaleOrderItem]) An array of objects representing the items in the sales order.
Payments (Array[Payment]) An array of objects representing any payments made on the order.
TaxCalculationResultId (GUID) Optional. The identifier of a tax calculation returned by the IQ Tax Service.
BillingAddressId (GUID) Optional. The identifier of a customer billing address record. Currently, this address is not validated.
ShippingAddressId (GUID) Optional. The identifier of a customer shipping address record. Currently, the address is not validated.
PrintableId (String) Required. An identifier from the external system that can be used to reference the order; for example, the online order confirmation number. This identifier is mentioned in the comments section of the RQ sales order and the invoices. Filterable. Maximum 50 characters.
DropshipOrderId (GUID) When the item type is Dropship, either DropshipOrderId or SupplierEntityId must be provided; forbidden otherwise. The identifier for this order in the Order service. Filterable.
UserId (Integer) Optional. Identifier of a valid user in RQ. This user must have sufficient permissions to create sales orders, add products, and create invoices at this location. Filterable.
ShippingLineItems (Array[ShippingLineItem]) Optional. A list of shipping line items associated with all or parts of this sales order.
DiscountLineItems (Array[DiscountLineItem]) Optional. A list of discount line items associated with all or parts of this sales order.

SaleOrderItem

Name Description
LineNumber (Integer) Required. The line number of the item. An incrementable integer greater than one. Must be unique within the list of items.
ProductCatalogId (GUID) Required. The identifier of the item in the iQmetrix Product Library.
Quantity (Integer) Required. The number of items of this type in the order.
Price (Decimal) Required. The price of the item.
PricingTermId (Integer) Optional. The identifier of a pricing term record.
CorrelationId (String) Optional. An identifier that can be used to correlate the item to an identifier in an external system. Although the Sales Order Service retains the full string, the string is trimmed to 30 characters when submitted to RQ.
ItemType (String) Required. The item type. Supported values are InStock (the item is in stock) or Dropship (the item is to be drop-shipped). When the item type is Dropship, either DropshipOrderId or SupplierEntityId must be provided.
SupplierEntityId (Integer) Required for Dropship item types; forbidden otherwise. The identifier of the supplier associated with the product.
SerialNumber (String) The serial number for a serialized product where the quantity is 1 or -1.
TaxLineItems (Array[TaxLineItem]) A list of taxes associated with all or parts of this sales order item.

TaxLineItems

Either all of TaxName, TaxableAmount, Rate, and Tax must be supplied, or else just IqmetrixTaxServiceId, but not both.

Name Description
TaxName (String) Required if IqmetrixTaxServiceId is not specified, forbidden otherwise. The name of the tax being applied.
TaxableAmount (Decimal) Required if IqmetrixTaxServiceId is not specified, forbidden otherwise.The taxable amount.
Rate (Decimal) Required if IqmetrixTaxServiceId is not specified, forbidden otherwise. The effective tax rate.
Tax (Decimal) Required if IqmetrixTaxServiceId is not specified, forbidden otherwise. The amount of tax charged.
IqmetrixTaxServiceId (GUID) Required if TaxName, TaxableAmount, Rate, and Tax are specified, forbidden if they are. The identifier of a tax query in the iQmetrix tax service.

Payments

The array is required, but can be empty if there are no payments.

Name Description
AuthCode (String) Optional. The authorization code for the payment.
TransactionNumber (String) Optional. The transaction number of the payment.
Token (String) Optional. The token associated with the payment.
Amount (Decimal) - Optional. The amount of the payment.  
CorrelationId (String) Optional. Correlates this payment with a payment record in another system. Although the Sales Order Service retains the full string, the string is trimmed to 30 characters when submitted to RQ.

Response

Example Response

HTTP 202 Content-Type: application/json
{
    "Id": "d8daa9df-0e3d-4355-b3f8-451b281b3be5",
    "DateCreatedUtc": "2018-01-04T16:00:00",
    "DateInsertedUtc": "0001-01-01T00:00:00",
    "DateUpdatedUtc": "0001-01-01T00:00:00",
    "CompanyId": 14146,
    "LocationId": 14192,
    "CustomerId": "a61ebc5a-b85f-66a3-dec3-260637dd796c",
    "ExpiryDateUtc": null,
    "Items": [
        {
            "LineNumber": 1,
            "ProductCatalogId": "55c8b270-63b9-a095-d975-9a730b3dacb4",
            "Quantity": 1,
            "Price": 99.98,
            "PricingTermId": 2,
            "CorrelationId": "6716053127",
            "ItemType": "InStock",
            "SupplierEntityId": null,
            "SerialNumber": null,
            "TaxLineItems": [
                {
                    "TaxName": "Sales Tax",
                    "TaxableAmount": 17.99,
                    "Rate": 0.0125,
                    "Tax": 0.22
                }
            ]
        }
    ],
    "Payments": [
		{
			"Id": "e4b25c1b-876a-4c13-b562-c3ba1ac33a76",
			"Amount" : 100.20,
			"AuthCode": "VISA_253189",
			"TransactionNumber": "DSX-39718",
			"Token": "OslkhrXM",
			"PaymentMethodId": "3500899B-22BB-426D-B642-1C0D6552D0AB",
			"CorrelationId" : "DSX-87924"
		}
	],
    "TaxCalculationResultId": "e4b25c1b-876a-4c13-b562-c3ba1ac33a76",
    "BillingAddressId": "1e93b1bc-ecf7-46f5-8be4-e20284e0df36",
    "ShippingAddressId": "8f49e60a-5714-4fd2-9d68-223114227011",
    "PrintableId": "229045",
    "DropshipOrderId": "9dd08bfc-24a0-99ed-64c4-8b5602402f91",
    "UserId": 4349,
    "ShippingLineItems": [
        {
            "LineNumber": 1,
            "Type": "USPS",
            "Amount": 9.99,
            "CorrelationId": "6716053127",
            "RetailerCatalogId": "a183f1a9-c58f-426a-930a-9a6357db52ed",
            "AssociatedLineItems": [
                1
            ]
        }
    ],
    "DiscountLineItems": [
        {
            "LineNumber": 1,
            "Amount": 2.99,
            "Name": "BOGO 50",
            "DiscountCode": "M5512323DD1",
            "AssociatedLineItems": [
                1
            ],
            "RetailerCatalogId": "a183f1a9-c58f-426a-930a-9a6357db52ed"
        }
    ]
}

A successful request returns a 200 (OK) response code with the completed object in the body of the response, represented as a SaleOrder resource. For a description of properties defined for the SaleOrder resource, see SaleOrder.

GET a Sales Order

Retrieves information for a particular sales order.

Request

GET /Companies({CompanyId})/SaleOrder({SaleOrderId})

Example Request

GET /Companies(14146)/SaleOrder(910de16b-471b-4d69-bde6-01109b24d89d)
Authorization: Bearer U3NkZsa-ZGZTRWRmU3JkZlNyBwsmGBFUJBkTUSc
Accept: application/json

Path Parameters

Name Description
CompanyId (Integer) The identifier of the company generating the sales order.
SaleOrderId(GUID) The identifier of the sales order.

Request Parameters

None.

Response

Example Response

HTTP 200 Content-Type: application/json
{
    "Id": "d8daa9df-0e3d-4355-b3f8-451b281b3be5",
    "DateCreatedUtc": "2018-01-04T16:00:00",
    "DateInsertedUtc": "0001-01-01T00:00:00",
    "DateUpdatedUtc": "0001-01-01T00:00:00",
    "CompanyId": 14146,
    "LocationId": 14192,
    "CustomerId": "a61ebc5a-b85f-66a3-dec3-260637dd796c",
    "ExpiryDateUtc": null,
    "Items": [
        {
            "LineNumber": 1,
            "ProductCatalogId": "55c8b270-63b9-a095-d975-9a730b3dacb4",
            "Quantity": 1,
            "Price": 99.98,
            "PricingTermId": 2,
            "CorrelationId": "6716053127",
            "ItemType": "InStock",
            "SupplierEntityId": null,
            "SerialNumber": null,
            "TaxLineItems": [
                {
                    "IqTaxServiceId": "fe73a2fd-1751-42a9-ac3d-d9d10e1317a4"
                }
            ]
        }
    ],
    "Payments": [
        {
            "Id": "e4b25c1b-876a-4c13-b562-c3ba1ac33a76",
            "Amount" : 100.20,
            "AuthCode": "VISA_253189",
            "TransactionNumber": "DSX-39718",
            "Token": "Unused",
            "PaymentMethodId": "3500899B-22BB-426D-B642-1C0D6552D0AB",
            "CorrelationId" : "DSX-87924"
        }
    ],
    "TaxCalculationResultId": "e4b25c1b-876a-4c13-b562-c3ba1ac33a76",
    "BillingAddressId": "1e93b1bc-ecf7-46f5-8be4-e20284e0df36",
    "ShippingAddressId": "8f49e60a-5714-4fd2-9d68-223114227011",
    "PrintableId": "229045",
    "DropshipOrderId": "9dd08bfc-24a0-99ed-64c4-8b5602402f91",
    "UserId": 52629,
    "ShippingLineItems": [
        {
            "LineNumber": 1,
            "Type": "USPS",
            "Amount": 9.99,
            "CorrelationId": "6716053127",
            "RetailerCatalogId": "a183f1a9-c58f-426a-930a-9a6357db52ed",
            "AssociatedLineItems": [
                1
            ]
        }
    ],
    "DiscountLineItems": [
        {
            "LineNumber": 1,
            "Amount": 2.99,
            "Name": "BOGO 50",
            "DiscountCode": "M5512323DD1",
            "AssociatedLineItems": [
                1
            ],
            "RetailerCatalogId": "a183f1a9-c58f-426a-930a-9a6357db52ed"
        }
    ]
}

A successful request returns a 200 (OK) response code with the requested sales order, represented as a SaleOrder resource. For a description of properties defined for the SaleOrder resource, see SaleOrder.

GET the Status of a Sales Order

Use the /SaleOrderStatus endpoint to retrieve the current status of a sales order. Submitting a GET request to the /SaleOrderStatus endpoint is the only way to retrieve this information, since the State property reporting sales order status is not included in the SaleOrder resource.

When a sales order is created, the system assigns it a status of Pending. The Pending status remains in effect for the lifetime of the sales order unless you manually update it to Cancelled or Completed.

Request

GET /Companies({CompanyId})/SaleOrderStatus({SaleOrderId})

Example Request

This example retrieves the status of sales order 94ec8140-4a8a-4b97-ad0a-c5c463694ca7.

GET /Companies(14146)/SaleOrderStatus(94ec8140-4a8a-4b97-ad0a-c5c463694ca7)
Authorization: Bearer U3NkZsa-ZGZTRWRmU3JkZlNyBwsmGBFUJBkTUSc_ABUpNTZQYwojP2A-VRcEFVZWIUcUFGsJICE5KgkpYUBXPx8iVAwYGQwhJhwX
Accept: application/json

Path Parameters

Name Description
CompanyId (Integer) Required. The identifier of the company generating the sales order.
SaleOrderId (GUID) Required. The identifier of the sales order whose status you want to determine.

Request Parameters

None.

Response

Example Response

HTTP 200 Content-Type: application/json
[
    {
    "Id": "c3a7fd2d-1882-4999-90c0-01b6d65ce29b",
    "State": "Pending",
    "UpdatedBy": 46920
}
]

A successful request returns a 200 (Ok) response code with the status information for the sales order.

Name Description
Id (GUID) The identifier of the sales order.
State (String) The status of the sales order. One of Pending, Completed, or Cancelled. Unless you update sales order status manually, the status is always Pending
UpdatedBy (Integer) The identifier of the user who made the most recent update to sales order status. If not set, this value is set to 0.

Update the Status of a Sales Order

The status of a sales order is always Pending unless you update it manually. A Pending order can be cancelled (set State to Cancelled) or completed (set State to Completed). Once cancelled or completed, the status can no longer be changed.

Request

PUT /Companies({CompanyId})/SaleOrderStatus({SaleOrderId})

Example Request

This example updates the status of sales order f6a4dc31-a91e-4866-97b8-024da773209a from Pending (its initial state) to Completed.

PUT /Companies(14146)/SaleOrderStatus(f6a4dc31-a91e-4866-97b8-024da773209a)
Authorization: Bearer U3NkZsa-ZGZTRWRmU3JkZlNyBwsmGBFUJBkTUSc
Content-Type: application/json
Accept: application/json

{
    "Id": "f6a4dc31-a91e-4866-97b8-024da773209a",
    "State": "Completed",
    "UpdatedBy": 236177
}

Path Parameters

Name Description
CompanyId (Integer) Required. The identifier of the company generating the sales order.
SaleOrderId (GUID) Required. The identifier of the sales order you want to update.

Request Parameters

Name Description
Id (GUID) Required. The identifier of the sales order.
State (String) Required. The status of the sales order. A sales order is assigned a status of Pending when it is created, and this status does not change unless you change it manually. You can change a status of Pending to Completed or Cancelled. Once changed to status of Completed or Cancelled, the status can no longer be changed.
UpdatedBy (Integer) Optional. The identifier of the user who made the update request. If not provided, this value is set to 0.

Response

Example Response

HTTP 200 Content-Type: application/json
[
    {
    "Id": "c3a7fd2d-1882-4999-90c0-01b6d65ce29b",
    "State": "Pending",
    "UpdatedBy": 46920
}
]

A successful request returns a 200 (Ok) response code with the status information for the sales order.

Name Description
Id (GUID) The identifier of the sales order.
State (String) The status of the sales order. One of Pending, Completed, or Cancelled.
UpdatedBy (Integer) The identifier of the user who made the update request.

GET Log Entries for a Specific Sales Order

If you have the identifier for a sales order, you can retrieve all log entries associated with it.

Request

GET /Companies({CompanyId})/SaleOrder({SaleOrderId})/StatusLog

Example Request

GET /Companies(14146)/SaleOrder(6dbec93e-e26c-49f8-b89e-1214c268fa31)/StatusLog
Authorization: Bearer U3NkZsa-ZGZTRWRmU3JkZlNyBwsmGBFUJBkTUSc
Accept: application/json

Path Parameters

Name Description
CompanyId (Integer) Required. The identifier of the company generating the sales order.
SaleOrderId (GUID) Required. The identifier of the sales order you want log entries for.

Request Parameters

None.

Response

Example Response

HTTP 200 Content-Type: application/json
[
    {
        "UpdatedBy": "Nathan",
        "Status": "Success",
        "Details": "Manually convert to invoice",
        "Id": "dfa2f09f-9de6-4cb6-a3e4-2e46ba6e5f6c",
        "UpdatedDate": "2017-07-17T10:35:00",
        "SaleOrderId": "dfa2f09f-9de6-4cb6-a3e4-2e46ba6e5f6c",
        "UserId": 0
    },
    {
        "UpdatedBy": "IntegrationTestFramework",
        "Status": "Failure",
        "Details": "One or more errors occurred.",
        "Id": "701b4462-2165-4a61-9adf-009a4c4670dd",
        "UpdatedDate": "2017-09-06T17:12:41.677",
        "SaleOrderId": "dfa2f09f-9de6-4cb6-a3e4-2e46ba6e5f6c",
        "UserId": 0
    }
]

A successful request returns a 200 (OK) response code with all the log entries associated with the sales order. For a definition of the fields returned in Status Log entries, see SaleOrderStatusLog. see SaleOrderStatusLog.

GET a Single Log Entry

If you have the identifier of a specific log entry, you can retrieve it from the Status Log. You will also need the identifier of the associated sales order.

Request

GET /Companies({CompanyId})/SaleOrder({SaleOrderId})/StatusLog({LogEntryId})

Example Request

GET /Companies(14146)/SaleOrder(6dbec93e-e26c-49f8-b89e-1214c268fa31)/StatusLog(dfa2f09f-9de6-4cb6-a3e4-2e46ba6e5f6c)
Authorization: Bearer U3NkZsa-ZGZTRWRmU3JkZlNyBwsmGBFUJBkTUSc
Accept: application/json

Path Parameters

Name Description
CompanyId (Integer) Required. The identifier of the Company generating the sales order.
SaleOrderId (GUID) Required. The identifier of the sales order you want log entries for. This identifier is returned in the response to the POST request that created the sales order.
LogEntryId (GUID) Required. The identifier of the log entry you want to retrieve.

Request Parameters

None.

Response

Example Response

HTTP 200 Content-Type: application/json
[
    {
        "UpdatedBy": "Nathan",
        "Status": "Success",
        "Details": "Manually convert to invoice",
        "Id": "dfa2f09f-9de6-4cb6-a3e4-2e46ba6e5f6c",
        "UpdatedDate": "2017-07-17T10:35:00",
        "SaleOrderId": "dfa2f09f-9de6-4cb6-a3e4-2e46ba6e5f6c",
        "UserId": 0
    }
]

A successful request returns a 200 (Ok) response code with the requested log entry. For a definition of the fields returned in Status Log entries, see SaleOrderStatusLog.

SEARCHING

The Sales Order API supports searching for fields in the SaleOrder and SaleOrderStatusLog resources. In principle, you should be able to filter on any field in the resource; in practice, test the properties of interest to you to ensure they are filterable.

Query Parameters

Query Operators

Not all comparison operators are applicable to all filter criteria; operator support depends on the data type of the field.

Operator Can Be Used With Examples
eq Integer, Boolean, String, Date UserId eq 0
Status eq 'Failure'
UpdatedDate eq DateTime'2017-09-13T18:44:55.233'
ge Integer, Date UserId ge 134
UpdatedDate ge DateTime'2017-09-13'
gt Integer, Date UserId gt 0
UpdatedDate gt DateTime'2017-09-13'
gte Integer, Date UserId gte 400
UpdatedDate lt DateTime'2017-09-13'
le Integer, Date UserId le 400
UpdatedDate lt DateTime'2017-09-13'
lt Integer, Date UserId lt 400
UpdatedDate lt DateTime'2017-09-13'
lte Integer, Date UserId lte 400
UpdatedDate lt DateTime'2017-09-13'
substringof String substringof('PrintableId', Details)

Examples

This example searches for the sales order with PrintableId 561341.

GET /Companies({CompanyId})/SaleOrder(3ff6e55b-1753-4c27-8b8e-3befa73b13c8)/StatusLog?$filter=Status eq 'Failure'&$skip=0&$top=5

Example Request

GET /Companies(14146)/SaleOrder(3ff6e55b-1753-4c27-8b8e-3befa73b13c8)/StatusLog?$filter=Status eq 'Failure'&$skip=0&$top=5
Authorization: Bearer U3NkZsa-ZGZTRWRmU3JkZlNyBwsmGBFUJBkTUSc
Accept: application/json

PAGINATION

https://salesorderdemo.iqmetrix.net/v1/Companies(14146)/SaleOrder(3ff6e55b-1753-4c27-8b8e-3befa73b13c8)/StatusLog?$skip=50&$top=100

Pagination in the Sales Order API is controlled by the $skip and $top query string parameters.

ERRORS

Error Code Description Reason
HTTP 400 A {x} is required when {y} is not provided See Message for details.
HTTP 400 {x} can not be null Ensure required parameters are provided.
HTTP 400 {x} can not be left blank Ensure required parameters are provided.
HTTP 400 {x} can not be left invalid Ensure required parameters are provided.
HTTP 400 {x} should not be empty Ensure required parameters are provided.
HTTP 400 Missing valid {x} Ensure required parameters are provided.
HTTP 400 {x} must be greater than 1 Ensure LineNumber properties are greater than 1.
HTTP 400 Products cannot have multiple of same tax defined Ensure each tax on item is unique.
HTTP 400 Multiple taxes cannot have the same {x} in the context of a product Ensure value is unique for each tax.
HTTP 403 Forbidden Contact support to check permissions for your user account.
HTTP 404 Not Found Ensure CompanyId is the one provided in onboarding package and SaleOrderId is valid.
Was this page helpful?