Item Fulfillment
An item fulfillment transaction records the shipment of some or all items on an order to the customer. The processes for item fulfillment transactions depend on whether the Advanced Shipping feature is enabled.
-
If Advanced Shipping is not enabled, the fulfillment and invoicing processes are combined. When an item fulfillment is created, a related invoice is created at the same time.
-
If Advanced Shipping is enabled, fulfillment and invoicing are two independent processes, and shipments can be recorded separately from billing.
Whether Advanced Shipping is enabled or not, order fulfillments should always be entered against sales orders to track the status of items and orders.
For more details about this type of transaction, see Order Fulfillment.
The item fulfillment record is defined in the tranSales (sales) XSD.
Supported Operations
The following operations can be used to manipulate the item fulfillment record.
add | addList | attach / detach | delete | deleteList | get | getDeleted | getList | getSavedSearch | getSelectValue | initialize / initializeList | search | update | updateList | upsert | upsertList
You can also use the asynchronous equivalents of SOAP web services list operations. For information about asynchronous operations, see SOAP Web Services Asynchronous Operations. For more information about request processing, see Synchronous Versus Asynchronous Request Processing.
Field Definitions
The SOAP Schema Browser includes definitions for all body fields, sublist fields, search filters, and search joins available to this record. For details, see the SOAP Schema Browser’s item fulfillment reference page.
For information about using the SOAP Schema Browser, see SOAP Schema Browser.
Usage Notes
Initializing Item Fulfillments
You can initialize an item fulfillment from a Sales Order, a Transfer Order, an Intercompany Transfer Order, or a Vendor Return Authorization.
The SOAP web services initialize operation emulates the UI workflow by prepopulating fields on transaction line items with values from a related record. For more information about this operation, see initialize / initializeList.
Item Fulfillment Workflow
When submitting an item fulfillment record, NetSuite can initialize this record on the server with data from the related transaction (such as a sales order) referenced in the createdFrom field. Then the item fulfillment record is updated with the itemList provided in your request and that data is validated against the initialized data from the referenced transaction.
Partial Fulfillments
The 2009.2 and earlier endpoints allow you to specify that only some of the line items in a referenced transaction should be fulfilled. The 2010.1 and later endpoints do not support partial fulfillments of line items from a transaction referenced in the createdFrom field. This behavior is consistent with item fulfillments in the UI and in SuiteScript.
Instead of using the createdFrom field, you can use the initialize operation to create an item fulfillment in SOAP web services. You can then get the item fulfillment record and specify which lines should be fulfilled before submitting the record.
Validation for Fed Ex or UPS related fields occurs after a record is routed to FedEx or UPS respectively and NOT by the NetSuite application as in the UI. Therefore, it is the responsibility of the client application developer to ensure that the correct fields are populated with the required information for shipping.
Accessing Serial/Lot or Bin Data for Line Items
As of the 2011.2 endpoint, code to access serial number, lot number, and bin number data varies according to whether the Advanced Bin Management / Numbered Inventory Management feature is enabled.
-
If this feature is enabled, you must use the 2011.2 endpoint or later to access the Inventory Detail subrecord and the most up-to-date bin and numbered inventory fields. You need to update any SOAP web services code from a previous endpoint that accesses these fields, to avoid errors or unexpected results.
-
If this feature is not enabled, you do not need to use the inventory detail record to access bin and numbered inventory fields and you do not need to update any related SOAP web services code from prior to 2011.2.
For more details, see Updating SOAP Web Services Code When Advanced Bin / Numbered Inventory Management is Enabled.
Sample Code
The following code illustrates adding a sales order record with a single item and then fulfilling that order. In this case, the account is set up for shipping with FedEx and FedEx is set as the method of shipping on the sales order record.
First, a sales order is created, set to the pendingFulfillment status, and populated with an itemList.
Create Sales Order Java
sessMgr.login();
SalesOrder salesOrder = new SalesOrder();
salesOrder.setEntity(Util.makeRecordRef("87", RecordType.customer));
salesOrder.setOrderStatus(SalesOrderOrderStatus._pendingFulfillment);
SalesOrderItem soi = new SalesOrderItem();
soi.setItem (Util.makeRecordRef("15", RecordType.inventoryItem));
soi.setQuantity(new Double (1));
soi.setAmount(new Double (14));
SalesOrderItemList soil = new SalesOrderItemList(new SalesOrderItem[]{soi}, true);
salesOrder.setItemList(soil);
salesOrder = sessMgr.getNetsuitePort().add(salesOrder);
Create Sales Order SOAP Request
<soapenv:Body>
<add xmlns="urn:messages_2017_1.platform.webservices.netsuite.com">
<record xsi:type="ns1:SalesOrder" xmlns:ns1="urn:sales_2017_1.transactions.webservices.netsuite.com">
<ns1:entity internalId="87 customer" xsi:type="ns2:RecordRef" xmlns:ns2="urn:core_2017_1.platform.webservices.netsuite.com"/>
<ns1:orderStatus xsi:type="ns3:SalesOrderOrderStatus" xmlns:ns3="urn:types.sales_2017_1.transactions.webservices.netsuite.com">_pendingFulfillment</ns1:orderStatus>
<ns1:itemList replaceAll="true" xsi:type="ns1:SalesOrderItemList">
<ns1:item xsi:type="ns1:SalesOrderItem">
<ns1:item internalId="15 inventoryItem" xsi:type="ns4:RecordRef" xmlns:ns4="urn:core_2017_1.platform.webservices.netsuite.com"/>
<ns1:quantity xsi:type="xsd:double">1.0</ns1:quantity>
<ns1:amount xsi:type="xsd:double">14.0</ns1:amount>
</ns1:item>
</ns1:itemList>
</record>
</add>
</soapenv:Body>
Using a Get operation on the sales order created above, the itemList information can be determined.
Get Sales Order SOAP Request
<soapenv:Body>
<get xmlns="urn:messages_2017_1.platform.webservices.netsuite.com">
<baseRef internalId="1505 salesOrder" xsi:type="ns1:RecordRef" xmlns:ns1="urn:core_2017_1.platform.webservices.netsuite.com"/>
</get>
</soapenv:Body>
Get Sales Order SOAP Response
<soapenv:Body>
<getResponse xmlns="urn:messages_2017_1.platform.webservices.netsuite.com">
<readResponse xmlns="urn:messages_2017_1.platform.webservices.netsuite.com">
<ns1:status isSuccess="true" xmlns:ns1="urn:core_2017_1.platform.webservices.netsuite.com"/>
<record internalId="1505" xsi:type="ns2:SalesOrder" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns2="urn:sales_2017_1.transactions.webservices.netsuite.com">
<ns2:entity internalId="87">
<ns3:name xmlns:ns3="urn:core_2017_1.platform.webservices.netsuite.com">Abe Simpson</ns3:name>
</ns2:entity>
<ns2:tranDate>2006-08-22T00:00:00.000-07:00</ns2:tranDate>
<ns2:tranId>SORD10069</ns2:tranId>
<ns2:orderStatus>_pendingFulfillment</ns2:orderStatus>
<ns2:salesRep internalId="43">
<ns4:name xmlns:ns4="urn:core_2017_1.platform.webservices.netsuite.com">Jon Baker</ns4:name>
</ns2:salesRep>
<ns2:leadSource internalId="-2">
<ns5:name xmlns:ns5="urn:core_2017_1.platform.webservices.netsuite.com">Ad</ns5:name>
</ns2:leadSource>
<ns2:excludeCommission>false</ns2:excludeCommission>
<ns2:isTaxable>false</ns2:isTaxable>
<ns2:toBePrinted>false</ns2:toBePrinted>
<ns2:toBeEmailed>false</ns2:toBeEmailed>
<ns2:email>asimpson@boo.com</ns2:email>
<ns2:toBeFaxed>false</ns2:toBeFaxed>
<ns2:billAddress>Abe Simpson<br>34 Elm St<br>Great Falls MT</ns2:billAddress>
<ns2:shipAddress>Abe Simpson<br>34 Elm St<br>Great Falls MT</ns2:shipAddress>
<ns2:shipDate>2006-08-22T00:00:00.000-07:00</ns2:shipDate>
<ns2:subTotal>14.0</ns2:subTotal>
<ns2:total>14.0</ns2:total>
<ns2:balance>0.0</ns2:balance>
<ns2:lastModifiedDate>2006-08-22T15:49:00.000-07:00</ns2:lastModifiedDate>
<ns2:status>Pending Fulfillment</ns2:status>
<ns2:itemList>
<ns2:item>
<ns2:item internalId="15">
<ns6:name xmlns:ns6="urn:core_2017_1.platform.webservices.netsuite.com">Tongue Depressor</ns6:name>
</ns2:item>
<ns2:quantity>1.0</ns2:quantity>
<ns2:price internalId="1">
<ns7:name xmlns:ns7="urn:core_2017_1.platform.webservices.netsuite.com">Base Price</ns7:name>
</ns2:price>
<ns2:rate>14.00</ns2:rate>
<ns2:amount>14.0</ns2:amount>
<ns2:commitInventory>_availableQty</ns2:commitInventory>
<ns2:isTaxable>true</ns2:isTaxable>
<ns2:isClosed>false</ns2:isClosed>
<ns2:line>1</ns2:line>
<ns2:quantityBackOrdered>0.0</ns2:quantityBackOrdered>
<ns2:quantityBilled>0.0</ns2:quantityBilled>
<ns2:quantityCommitted>1.0</ns2:quantityCommitted>
<ns2:quantityFulfilled>0.0</ns2:quantityFulfilled>
</ns2:item>
</ns2:itemList>
</record>
</readResponse>
</getResponse>
</soapenv:Body>
Item Fulfillment Java
Next the sales order created above is referenced by setting the createdFrom field to the internalId of the sales order. The specific items to be fulfilled are referenced by setting the Line field to the desired item line from the sales order.
ItemFulfillment itemFulfillment = new ItemFulfillment();
itemFulfillment.setCreatedFrom(Util.makeRecordRef(salesOrder.getInternalId(), RecordType.salesOrder));
ItemFulfillmentItemList ifil = new ItemFulfillmentItemList();
ItemFulfillmentItem ifi = new ItemFulfillmentItem();
ifi.setOrderLine(salesOrder.getItemList().getItem(0).getLine());
ifil.setItem(new ItemFulfillmentItem[]{ifi});
itemFulfillment.setItemList(ifil);
itemFulfillment = sessMgr.getNetsuitePort().add(itemFulfillment);
Item Fulfillment SOAP Request
<soapenv:Body>
<add xmlns="urn:messages_2017_1.platform.webservices.netsuite.com">
<record xsi:type="ns1:ItemFulfillment" xmlns:ns1="urn:sales_2017_1.transactions.webservices.netsuite.com">
<ns1:createdFrom internalId="1505 salesOrder" xsi:type="ns2:RecordRef" xmlns:ns2="urn:core_2017_1.platform.webservices.netsuite.com"/>
<ns1:itemList replaceAll="false" xsi:type="ns1:ItemFulfillmentItemList">
<ns1:item xsi:type="ns1:ItemFulfillmentItem">
<ns1:orderLine xsi:type="xsd:long">1</ns1:orderLine>
</ns1:item>
</ns1:itemList>
</record>
</add>
</soapenv:Body>
Item fulfillment creation is affected by the preference set at Setup > Accounting > Accounting Preferences > Order Management tab > Fulfillment Based on Commitment. The best practice for creating an item fulfillment in SOAP web services is to use the initialize operation, as it returns the item fulfillment with all the defaults set and users will not have to specify the item quantities themselves. Following this practice prevents users from generating a partially fulfilled order without knowing it. (See initialize / initializeList in the NetSuite Help Center for details on this operation.)