Skip to content

CartService

← Developer Documentations

Release Date: 3/26/2018

Web Services CartService provides methods to support an e-commerce shopping cart.  It is expected more methods will be provided over time to support necessary shopping cart processing.  Currently, these services and methods are scattered in other web services.  As of this writing, the following methods are supported.

  •  GetSalesTax

GetSalesTax

This method provides sales tax information for a shopping cart. The typical use case is to retrieve sales tax information and present them to the user during checkout, before the order is created.

This method can be used to retrieve just the tax rates. It can also be used to retrieve the tax rates and calculated tax amount. In most cases, you will want the web service to return the calculated tax amount. This is because the tax calculation could get complicated even if all the tax rates information is given.

To get the tax rate, the caller must provide at least one of the following pieces of the information:

  1.  Customer Number
  2.  Customer + Ship to number
  3.  Ship to postal code

To get the sales tax rate and get the calculated tax amount, the caller must also specify the taxable amount. This can be done by specifying one of the following pieces of information:

  1.  FreightAmount (CartRequest. ORD_FREIGHT_AMOUNT),
  2.  MiscChargeAmount (CartRequest. ORDER_MISC_CHRG_AMT) if applicable,
  3.  SalesAmount. To specify the SalesAmount, you specify one of the following: CartRequest. ORDER_TOTAL_SALE_AMT, or CartRequest. ORDER_TOTL_TAXBL_AMT, or specify the items in the shopping cart via CartRequest.CartItems/

Example: You have the zip code and you know the total sale amount and freight amount. You want to find out the sales tax amount.  Since different tax jurisdictions may treat freight taxable status differently, passing the freight amount will allow Elliott back end logic to calculate the tax amount accurately.

/// <summary>
/// Retrieve sales tax by postal code and total sale amount
/// </summary>
public void GetSalesTaxByPostalCodeAndTotalSaleAmount() {
  using (var client = new CartService.CartServiceSoapClient()) {
    // setup reqeust
    var request = new CartService.CartRequest();
    request.ORDER_SHIP_TO_ZIPCD = "91789";
    request.ORDER_TOTAL_SALE_AMT = 100;
    request.ORD_FREIGHT_AMOUNT = 10;

    var response = client.GetSalesTax(request);

    // Act on response
    if (response.ReturnCode != 0) {
      // TODO: handle error
    }
    Console.WriteLine($"total sales tax: {response.OrderTotalTaxAmount}");
  }
}

Example: You have the zip code and the items in the shopping cart. You want to find out the sales tax amount.

/// <summary>
/// Retrieve sales tax by postal code and cart items
/// </summary>
public void GetSalesTaxByPostalCodeAndCartItems() {
  Console.WriteLine($"Running {System.Reflection.MethodInfo.GetCurrentMethod().Name}.");

  using (var client = new CartService.CartServiceSoapClient()) {
    // setup reqeust
    var request = new CartService.CartRequest();
    request.ORDER_SHIP_TO_ZIPCD = "91789";
    var items = new List<CartService.CartItem>();
    items.Add(new CartService.CartItem() {
      LINE_ITM_ITEM_NO = "5249A",
      LINE_ITM_QTY_ORDRD = 1
    });
    request.CartItems = items.ToArray();

    var response = client.GetSalesTax(request);

    // Act on response
    if (response.ReturnCode != 0) {
      // TODO: handle error
    }
    Console.WriteLine($"total sales tax: {response.OrderTotalTaxAmount}");
  }
}

Example: You have the customer number. You do not know the sales amount and freight amount. You want to know the sales tax rates, tax codes and related flags. Note: Normally you would want the tax caculated by the web service.

public void GetSalesTaxRateByCustomer() {
  using (var client = new CartService.CartServiceSoapClient()) {
    var request = new CartService.CartRequest();
    request.ORDER_CUSTOMER_NO = "007020";
    var response = client.GetSalesTax(request);
    if (response.ReturnCode != 0) {
      // TODO: handle error
    }
    Console.WriteLine($"taxable: {response.IsTaxableFlag}");
    Console.WriteLine($"state tax code: {response.ORDER_TAX_CODE_1}");
    Console.WriteLine($"state tax percent: {response.ORDER_TAX_PERCENT_1}");
    Console.WriteLine($"state tax include freight: {response.OrderTax1FreightFlag}");
    Console.WriteLine($"state tax include misc charge: {response.OrderTax1MiscChargeFlag}");
    Console.WriteLine($"county tax code: {response.ORDER_TAX_CODE_2}");
    Console.WriteLine($"county tax percent: {response.ORDER_TAX_PERCENT_2}");
    Console.WriteLine($"county tax include freight: {response.OrderTax2FreightFlag}");
    Console.WriteLine($"county tax include misc charge: {response.OrderTax2MiscChargeFlag}");
    Console.WriteLine($"city tax code: {response.ORDER_TAX_CODE_3}");
    Console.WriteLine($"city tax percent: {response.ORDER_TAX_PERCENT_3}");
    Console.WriteLine($"city tax include freight: {response.OrderTax3FreightFlag}");
    Console.WriteLine($"city tax include misc charge: {response.OrderTax3MiscChargeFlag}");
  }
}

Override EliorderService.CreateOrder Sales Tax Calculation for M iscellaneous C ustomer


Miscellaneous customers are customer numbers that start with "*" (Aesteric) like "*XXXX."  A miscellaneous customer account is a shared account for miscellaneous orders from multiple "customers" where the actual "customer" is stored as an eContact attached to the customer record.

If you are using EliorderService.CreateOrder to create orders for miscellaneous customers, you should override the tax calculation. EliorderService.CreateOrder uses the tax settings on the customer record to calculate sales tax. For regular customers, this works as expected. For miscellaneous customers, the sales tax might be incorrect since the ship-to address and tax settings on the customer record is not the same as the actual customer. 

To override the sales tax, first call CartService.GetSalesTax. Then when you call EliorderService.CreateOrder method, override the following properties in the request with the ones you got back from GetSalesTax method:

ORD_SALES_TAX_AMT_1
ORDER_TAX_CODE_1
ORDER_TAX_PERCENT_1
ORD_SALES_TAX_AMT_2
ORDER_TAX_CODE_2
ORDER_TAX_PERCENT_2
ORD_SALES_TAX_AMT_3
ORDER_TAX_CODE_3
ORDER_TAX_PERCENT_3

CartRequest Structure


Property Name

Length

Type

Upper

Detail

AchPayments

 

CartAchPayment[]

 

Not Used

Attributes

 

CartAttribute[]

 

Not Used

CartItems

 

CartItem[]

 

Specify the items in the shopping cart. The items will be used to calculate the taxable sales amount.

There are multiple ways caller can specify the taxable sales amount for the items in shopping cart, CartItems, ORDER_TOTL_TAXBL_AMT, ORDER_TOTAL_SALE_AMT, listed in the order they are considered.

Contacts

 

CartContact[]

 

Not Used

CreditCardPayments

 

CartCreditCardPayment

 

Not Used

ErrorDupPoFlag


String


Not Used

Notes

 

CartNote[]

 

Not Used

ORD_BILL_TO_COUNTRY

 

String   

 

Not Used

ORD_FREIGHT_AMOUNT

 

Decimal

 

Freight Amount. If freight is taxable, it will be included in the calculated tax amount.

ORD_SHIP_TO_COUNTRY

 

String

 

Not Used

ORDER_BILL_TO_ADDR_1

 

String

 

Not Used

ORDER_BILL_TO_ADDR_2

 

String

 

Not used

ORDER_BILL_TO_CITY

 

String

 

Not Used

ORDER_BILL_TO_NAME

 

String

 

Not Used

ORDER_BILL_TO_NO

 

String

 

Not used

ORDER_BILL_TO_ST

 

String

 

Not Used

ORDER_BILL_TO_ZIPCD

 

String

 

Not used

ORDER_CHECK_DATE

 

Date

 

Not used

ORDER_CHECK_NO

 

Integer

 

Not Used

ORDER_COMMENT1

 

String

 

Not Used

ORDER_COMMENT2

 

String

 

Not Used

ORDER_COMMENT3

 

String

 

Not Used

ORDER_CUSTOMER_NO

 

String

 

Specify the customer number for tax calculation. The specified customer’s tax rates will be used for tax calculation.

Depends on the input, tax rates are calculated differently. The following are the possible inputs, listed in the order that are considered: ORDER_CUSTOMER_NO + ORDER_SHIP_TO_NO, ORDER_CUSTOMER_NO, ORDER_SHIP_TO_ZIPCD

ORDER_EDI_EXP_FLG

 

String

 

Not Used

ORDER_EDI_FLAG

 

String

 

Not Used

ORDER_FRGHT_PAY_CODE

 

String

 

Not Used

ORDER_JOB_NO

 

String

 

Not Used

ORDER_MFGING_LOC

 

String

 

Not Used

ORDER_MISC_CHRG_AMT

 

Decimal

 

Miscellaneous charge amount. If misc charge is taxable, it will be included in the calculated tax amount.

ORDER_PAYMENT_AMOUNT

 

Decimal

 

Not Used

ORDER_PAYMENT_TP

 

String

 

Not Used

ORDER_PROFIT_CENTER

 

String

 

Not Used

ORDER_PURCH_ORDER_NO

 

String

 

Not Used

ORDER_SALESMAN_NO_1

 

String

 

Not Used

ORDER_SALESMAN_NO_2

 

String

 

Not Used

ORDER_SALESMAN_NO_3

 

String

 

Not Used

ORDER_SHIP_TO_ADDR_1

 

String

 

Not Used

ORDER_SHIP_TO_ADDR_2

 

String

 

Not Used

ORDER_SHIP_TO_CITY

 

String

 

Not Used

ORDER_SHIP_TO_NAME

 

String

 

Not Used

ORDER_SHIP_TO_NO

 

String

 

Specify the ship-to number for tax calculation. The specified ship-to tax rates will be used for tax calculation. Must also specify the ORDER_CUSTOMER_NO.

See ORDER_CUSTOMER_NO.

ORDER_SHIP_TO_ZIPCD

 

String

 

Specify the ship-to zip code. The specified zip code location (state, county, city) tax rates will be used for calculation.

See ORDER_CUSTOMER_NO.

ORDER_SHIP_VIA_CODE

 

String

 

Not Used

ORDER_SHIPPING_DATE

 

Date

 

Not Used

ORDER_SLS_PCT_COMM_1

 

Decimal

 

Not Used

ORDER_SLS_PCT_COMM_2

 

Decimal

 

Not Used

ORDER_SLS_PCT_COMM_3

 

Decimal

 

Not Used

ORDER_TAX_CODE_1

 

String

 

Not Used

ORDER_TAX_CODE_2

 

String

 

Not Used

ORDER_TAX_CODE_3

 

String

 

Not Used

ORDER_TAX_PERCENT_1

 

Decimal

 

Not Used

ORDER_TAX_PERCENT_2

 

Decimal

 

Not Used

ORDER_TAX_PERCENT_3

 

Decimal

 

Not Used

ORDER_TERMS_CODE

 

String

 

Not Used

ORDER_TOTAL_SALE_AMT

 

Decimal

 

Specify the total sales amount for tax calculation.

See CartItems.

ORDER_TOTAL_WEIGHT

 

Decimal

 

Not Used

ORDER_TOTL_TAXBL_AMT

 

Decimal

 

Specify the total taxable sales amount for tax calculation.

See CartItems.

ORDER_TYPE

 

String

 

Not Used

OrderInstruction

 

String

 

Not Used

OrderTimeRelease

 

Integer

 

Not Used

SendConfirmationEmail

 

String

 

Not Used

UseAutoFreight

 

String

 

Not Used

UseAutoMiscChrg

 

String

 

Not Used

VendorNo

 

String

 

Not Used

VoucherNo

 

String

 

Not Used

CartItem Structure

Property Name

Length             

Type

Upper

Detail

Attributes

 

CartAttribute[]

 

Not Used

IMHLTFIL_TRX_ID

 

Decimal

 

Not Used

LINE_ITM_DESC1

 

String

 

Not Used

LINE_ITM_DESC2

 

String

 

Not Used

LINE_ITM_DISC_PCT

 

Decimal

 

Not Used

LINE_ITM_EDI_TURNAR

 

String

 

Not Used

LINE_ITM_ITEM_NO

 

String

 

Specify the item number.

LINE_ITM_ORG_ITM_NO

 

String

 

Not Used

LINE_ITM_PROD_CATE

 

String

 

Not Used

LINE_ITM_PROMISE_DT

 

Date

 

Not Used

LINE_ITM_QTY_BCK_ORD

 

Decimal

 

Not Used

LINE_ITM_QTY_ORDRD

 

Decimal

 

Specify the quantity ordered.

LINE_ITM_QTY_TO_SHIP

 

Decimal

 

Not Used

LINE_ITM_REASON_CODE

 

String

 

Not Used

LINE_ITM_REQST_DATE

 

Date

 

Not Used

LINE_ITM_SERL_LOT_NO

 

String

 

Not Used

LINE_ITM_UNIT_PRICE

 

Decimal

 

Not Used

LINE_ITM_UOM

 

String

 

Not Used

LINE_ITM_VENDOR_NO

 

String

 

Not Used

Notes

 

CartNote[]

 

Not Used

UseSetDiscPct

 

String

 

Not Used

UseSetUnitPrice

 

String

 

Not Used

 

CartResponse Structure
 

Property Name

Type

Detail

IsTaxableFlag

String

“Y” or “N” flag. Indicate whether the order will be taxable.

ORD_FREIGHT_AMOUNT

Decimal

Not Used

ORD_SALES_TAX_AMT_1

Decimal

Indicate state sales tax amount

ORD_SALES_TAX_AMT_2

Decimal

Indicate county sales tax amount

ORD_SALES_TAX_AMT_3

Decimal

Indicate city sales tax amount

ORDER_BILL_TO_NAME

String

Not Used

ORDER_BILL_TO_NO

String

Not used

ORDER_COMM_AMOUNT

Decimal

Not Used

ORDER_COMM_PERCENT

Decimal

Not Used

ORDER_CUSTOMER_NO

String

Not Used

ORDER_DATE

Date

Not Used

ORDER_DATE_ENTERED

Date

Not Used

ORDER_DEPT_NO

String

Not Used

ORDER_EDI_FLAG

String

Not Used

ORDER_JOB_NO

String

Not Used

ORDER_MFGING_LOC

String

Not Used

ORDER_MISC_CHRG_AMT

Decimal

Not Used

ORDER_NO

Integer

Not Used

ORDER_ORD_ACK_SENT

String

Not Used

ORDER_PHANTM_INV_FLG

String

Not Used

ORDER_RMA_STATUS

String

Not Used

ORDER_SALESMAN_NO_1

String

Not Used

ORDER_SHIP_TO_NAME

String

Not Used

ORDER_SHIP_TO_NO

String

Not Used

ORDER_SHIP_TO_XREF

String

Not Used

ORDER_SHIP_VIA_CODE

String

Not Used

ORDER_SHIPPING_DATE

Date

Not Used

ORDER_STORE_NO

String

Not Used

ORDER_TAX_CODE_1

String

Indicate the state sales tax code. Blank if no configured state sales tax.

ORDER_TAX_CODE_2

String

Indicate the county sales tax code. Blank if no configured county sales tax.

ORDER_TAX_CODE_3

String

Indicate the city sales tax code. Blank if no configured city sales tax

ORDER_TAX_PERCENT_1

Decimal

Indicate state sales tax percentage.

ORDER_TAX_PERCENT_2

Decimal

Indicate county sales tax percentage.

ORDER_TAX_PERCENT_3

Decimal

Indicate city sales tax percentage.

ORDER_TERMS_CODE

String

Not Used

ORDER_TOTAL_SALE_AMT

Decimal

Not Used

ORDER_TOTAL_WEIGHT

Decimal

Not Used

ORDER_TYPE

String

Not Used

OrderBillToCity

String

Not Used

OrderBillToState

String

Not Used

OrderBillToZipCode

String

Not Used

OrderHoldStatus

String

Not Used

OrderLineItems

CartOrderLineItem[]

Not Used

OrderPurchaseNo

String

Not Used

OrderShipToCity

String

Not Used

OrderShipToState

String

Not Used

OrderShipToZipCode

String

Not Used

OrderTax1FreightFlag

String

“Y” or “N” flag. Indicate whether freight is taxable in state sales tax.

OrderTax1MiscChargeFlag

String

“Y” or “N” flag. Indicate whether miscellaneous charge is taxable in state sales tax.

OrderTax2FreightFlag

 String

“Y” or “N” flag. Indicate whether freight is taxable in county sales tax.

OrderTax2MiscChargeFlag

 String

“Y” or “N” flag. Indicate whether miscellaneous  is taxable in county sales tax.

OrderTax3FreightFlag

 String

“Y” or “N” flag. Indicate whether freight is taxable in city sales tax.

OrderTax3MiscChargeFlag

 String

“Y” or “N” flag. Indicate whether miscellaneous charge is taxable in city sales tax.

OrderTotalTaxAmount

 Decimal

Indicate the total sales tax amount. This is the sum of ORD_SALES_TAX_AMT_1 + ORD_SALES_TAX_AMT_2 + ORD_SALES_TAX_AMT_3

SplitOrders

CartOrder[]

Not Used

CartResponse ReturnCode


CartResponse.ReturnCode indicates the status of the operation. The following are the possible codes. CartResponse.ReturnMsg describes the status of the operation in text. In case of errors, it also provides additional information about the error.

0 = Success. The operation was successful.

100 = InvalidRequest. The operation was not successful. The request is invalid.

200 = Application Error. The operation was not successful. There was an application error. This type of error is due to an error on the server side. This could either by an application error that needs to be fixed by code. Or it could be a temporary error with the server environment (e.g., network issue, database server offline, etc).


VYC


Feedback and Knowledge Base

(thinking…)