Skip to content

Orders & Cart

Covers OrderImport, ShipToImport, and GetCartSummary — the write-oriented OrderServices messages plus the pre-checkout pricing preview call.

See eCommerce API overview for the shared envelope fields and result codes.

OrderImport

Creates a new order (or quote, if ImportAsQuote=TRUE) from the storefront cart. This is an asynchronous import, not a synchronous create — see the warning below.

Request Fields (header level)

Field Required Notes
CustomerCode Yes Must be a valid, existing P21 customer.
Anonymous Yes Hardcode N.
PONumber No
RequireDate No Header-level required date; used if no line-level RequireDate is set.
ContractUID No Ties the whole order to a contract.
ImportAsQuote Yes TRUE imports as a quote instead of a live order.
QuoteNumber No Populate when converting an existing quote to an order.
UseContractAddress Yes Hardcode False.
WillCall No TRUE for will-call orders. A ship-to ID is still required even for will-call.
PackingBasis No Must be a valid P21 packing basis value.
BlindShip / BlindShipFlag No TRUE marks the order blind-ship.
FreightCode No "Other charge item" code P21 uses to add a freight line.
FreightAmount / FreightOut No Freight amount to charge, tied to FreightCode.
UseSystemSettingForPricingUnit Yes Hardcode TRUE.
NotepadText / NotepadDisplayArea No Header-level order note. NotepadDisplayArea controls where in P21 the note surfaces (Order Entry, Print Invoices, RMA Entry, etc. — pipe-delimited for multiple).
ContactID No Link the order to a P21 contact.
CarrierAccountNumber, ThirdPartyBillingCode No Present in the current schema, not documented in the 2013 manual — third-party freight billing fields.
DeliveryPoint No Undocumented in the manual.
Allocate No Undocumented in the manual — likely controls whether inventory is allocated immediately on import.
WebShopperId, WebShopperEmailAddress No Requires B2BSeller; identifies the logged-in web shopper for attribution/audit, distinct from CustomerCode (which may be a shared house account).

CustomerShipTo block

Field Required Notes
ShipToID No If populated, P21 uses the address on file for that ship-to and ignores the address fields below. If blank, the order gets a free-form, one-time ship-to built from ShipToAddress — not linked to the customer record.
ShipToAddress/ShipToCompanyName,Address1-3,City,State,Zip,Country Conditional Required if ShipToID is blank. ShipToState must be a 2-character code.
ShipToContactFirstName/LastName/Salutation/Title/Phone/Fax/EMail No
ShipToCarrierId No Shipping method ID (carrier) from P21.
ShipToInstruction No Present in current schema, undocumented in manual.

CreditCard block

Only needed for credit-card orders. Notably, CardNumber is documented to hold only the last 4 digits — full PAN capture/tokenization is handled by Element (the payment processor referenced throughout), not P21 directly.

Field Notes
CardType Must match a payment_type.payment_type_id in P21.
CardNumber Last 4 digits only.
ExpirationMonth / ExpirationYear
AuthorizationCode Populate if the website already authorized the card.
ElementPaymentAccountID Token representing a stored card.
ElementTransactionID If populated, P21 uses this pre-existing Element authorization at final sale. If blank, P21 performs the authorization itself during import — a meaningful behavioral fork worth testing explicitly.
ElementProcessorID Must exist in creditcard_processor.creditcard_processor_uid.
CardHolder/FirstName,LastName,Address/* Billing name/address tied to the card.
AVSResponseCode, CVVResponseCode Optional, informational.
SwitchIssueNumber, RealexReferenceNumber, RealexOrderID, CommercialCardResponseCode, CardBrand Present in current schema, undocumented — alternate processor (Realex) and commercial-card fields, likely dormant unless that processor is configured.

ListOfLineItems/LineItem

Field Required Notes
ItemID Yes inv_mast.item_id.
OrderQuantity Yes
UnitName / UnitSize Yes Must be a valid UOM for the item.
UnitPrice No Leave blank for P21 to calculate; populate to force a specific price.
SourceLocation Yes Location to source the line from.
RequireDate No Overrides header RequireDate for this line.
ContractUID No If the line was priced from a job contract.
CustomerPartNumber No
OrderedAs Yes Leave blank — reserved.
QuoteLineNumber / QuoteLineComplete No For quote-to-order conversion.
NotepadText / NotepadDisplayArea No Line-level note, same display-area values as the header note.
NewWebItem, BinID, Description, ExtendedDescription, SupplierID, CalculateTax, MinimumSurchargeItem, CarrierID, IncomingFreight, GLCode No Requires B2BSeller / a specific P21 custom feature — not supported on all P21 versions.

Other request sections

  • ListOfMerchandiseCredits/MerchandiseCredit/MerchandiseCreditNumber,Amount — only if merchandise credit pays for part of the order.
  • ListOfCoupons/Coupon/CouponNumber
  • EFTInformation/EFTAccountNumber,EFTRoutingNumber,EFTBankName,EFTBankCity,EFTBankState,ETFTaxpayerAccountID — ACH/EFT payment, undocumented in the manual.

Reply

<Reply>
  <OrderNumber />
</Reply>

OrderImport is asynchronous — check whether SISM is running

P21's Scheduled Import Service Manager (SISM) processes the import queue. If SISM is running, OrderNumber comes back populated on the same response. If SISM is not running, OrderNumber comes back blank — P21 has staged the import data, but the order itself won't exist until SISM next runs. Don't treat a blank OrderNumber as a failure; check ReplyStatus/Result first, and if it's 0, the import was accepted even though the order number isn't known yet. If your storefront needs the order number synchronously (e.g. for an order confirmation page), you'll need to poll or otherwise account for this gap.

ShipToImport

Creates a new ship-to record independent of placing an order (e.g. "add an address" in account management).

No XML template supplied

Unlike the other messages in this section, no .xml template for ShipToImport was included in the files handed off — the request/reply structure below comes entirely from the 2013 manual. Treat the field list as a starting point and verify it against the live schema (XBGShipToImport.xsd) before building against it.

Request Fields

Field Required Notes
CustomerCode Yes
ShipToAddress/ShipToCompanyName,Address1-3,City,State,Zip,Country Yes ShipToState is a 2-character code.
ShipToContactFirstName/LastName/Salutation/Title/Phone/Fax/EMail No
ShipToCarrierID No

Reply

<Reply>
  <ShipToID />
</Reply>

GetCartSummary

Prices an entire cart — line items, discounts, freight, tax, and other charges — before the shopper checks out. Effectively OrderImport's pricing/tax engine exposed as a preview call, so the storefront can show an accurate order total without actually creating anything.

Second-pass discounting and tax are your integration's responsibility to wire up

Per the manual: "A taxing procedure will need to be written. Second Pass Discounting must be implemented." This message doesn't calculate tax or apply second-pass discounts out of the box — those are configured/implemented separately in the P21 environment.

Request Fields (header level)

Field Required Notes
PONumber, ShipToID No
PaymentMethod No
ContractUID, SalesRepID No
CartRequiredDate No
GetCostType, UseSystemSettingForPricingUnit No Same semantics as GetItemPrice.
SourceLocations/IncludeExclude + ListOfLocations No Same as GetItemPrice.
AllCompaniesWideAvailability, GetCompanyAvailability No
GetRemainingFreeQuantity, GetListOfItemLocationQuantities No Same as GetItemPrice.
ProcessMinimumOrderCharge No Triggers minimum-order-charge logic in the summary.
PromoCode No
OrderTotalStartDate/OrderTotalEndDate No Undocumented in the manual — likely scopes a historical order-total lookup, mirroring the same field pair on GetCustomerControl.
CustomerShipTo/ShipToAddress/ShipToZip No A free-form ship-to zip for tax calculation when no ShipToID is set yet.
ListOfCoupons/Coupon/CouponNumber No
ListOfOutgoingCarriers/OutgoingCarrier/CarrierID No

ListOfLineItems/LineItem

Same core fields as OrderImport lines (ItemID, OrderQuantity, UnitName, UnitSize, UnitPrice, SourceLocation, ContractUID, RequireDate), plus:

Field Notes
SourceFromAlternateLocations Let P21 source from a different location if SourceLocation can't fulfill.
GetPriceBreaks Same as GetItemPrice — set to include break data for this line.
ShoppingCartDetailUID Your own cart line identifier, echoed back — use it to match reply lines to your cart state.
AuxiliaryData/PricePageUID, CheckRestrictions
CarrierID, WeeklyTruck

Reply — CartSummary (the totals block)

Field Notes
TotalLineItemAmount Sum of all line extended prices.
Discounts
Freight
OtherCharges / OtherChargesDescription
SalesTax / OtherTax / TaxOnFreight
TotalInvoiceAmount The number to show the shopper as their order total.
RequiredDate
ListOfFailedItems/FailedItem/ItemCode,ErrorCode,ErrorMessage Check this even when ReplyStatus/Result is 0. Individual lines can fail (bad item, no availability, etc.) without failing the whole cart-pricing call.
OrderTotal

Reply — per-line (ListOfLineItems/LineItem)

Mirrors GetItemPrice's reply shape (NetPrice, ExtendedPrice, FreeQuantity, LeadTimeDays, BreakID, ListOfBreaks, PricedByContract, ListOfItemLocationQuantities), plus cart-specific fields:

Field Notes
Discount Discount applied to this line.
AllocatedQuantity / BackorderedQuantity
Disposition
ListOfRelations/Relation GOTOGETHER / SUBSTITUTE tags for cross-sell, inline (same idea as GetRelatedItems but returned as part of cart pricing).
OverBudget, BudgetCd, BudgetDollarLimit, BudgetDollarLimitUsed, BudgetDollarLimitRemaining Customer budget-limit enforcement, if configured.
Tax Tax for this specific line.
MinimumSurchargeItem, MinimumOrderAmount, MinimumGallonAmount Minimum-order-charge inputs (see ProcessMinimumOrderCharge above).
FreightIn, Revision, SalesRepCommissionCost, SalesRepCommissionCostGP Present in current schema, undocumented in the manual.

Example

<GetCartSummary xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="C:\XBG\Schemas\XBGCart_(PreOrderSummary).xsd">
  <Request>
    <B2BSellerVersion><MajorVersion>5</MajorVersion><MinorVersion>11</MinorVersion><BuildNumber>145</BuildNumber></B2BSellerVersion>
    <StoreName>T</StoreName>
    <CustomerCode>100437</CustomerCode>
    <WebReferenceNumber>2012430</WebReferenceNumber>
    <GetCompanyAvailability>False</GetCompanyAvailability>
    <UseSystemSettingForPricingUnit>TRUE</UseSystemSettingForPricingUnit>
    <GetListOfItemLocationQuantities>TRUE</GetListOfItemLocationQuantities>
    <ListOfLineItems>
      <LineItem>
        <ItemID>B2BITEM3</ItemID>
        <OrderQuantity>1</OrderQuantity>
        <UnitName>EA</UnitName>
        <UnitSize>1.0000</UnitSize>
        <SourceLocation>1006840</SourceLocation>
        <GetPriceBreaks>1</GetPriceBreaks>
        <ShoppingCartDetailUID>16925</ShoppingCartDetailUID>
      </LineItem>
    </ListOfLineItems>
  </Request>
  <Reply />
  <ReplyStatus><Result>0</Result><Message /></ReplyStatus>
</GetCartSummary>