Purpose: You can use the integration with Narvar in order to have Narvar generate shipment confirmation and delivery update emails to customers.
In this topic:
• Narvar Order Request Message
• Mapping
• Sample Order Request Message
Purpose: When the Use Narvar Integration (M57) system control value is selected, Order Management System sends an order request message to Narvar when the shipment is processed by the BILL_ASYNC job. This message includes information about:
• The sold-to customer and the shipping address.
• Each item on the order, including items that have not yet been fully shipped or that were shipped previously.
• The shipment(s) made, including the ship via and tracking number.
• The warehouse that shipped the item(s).
For more information: See the Narvar Order Request Message for details.
Messages from Narvar to the customer generated when? Narvar generates notification to the customer using the information provided in the order request message based on updates from the carrier; for example, the customer might receive an email indicating that the package is on its way, or has been delivered.
Other email generation settings do not apply: When Narvar integration is in use:
• The order request messages for shipment confirmations are sent to Narvar only through billing. Other options for generating emails, such as Sending Internet Order Ship Confirmation (ESCF), do not generate shipment confirmation emails, regardless of the setting of the Send Shipment Confirmation from Billing (L98) system control value.
• The CWEmailOut message is not generated for shipment confirmations.
• The shipment email templates set up through Working with E-Mail Notification Templates (WEMT) are not used.
• The settings set up for the order type through the Order Type Email Selection Screen and Order Type Email Template Screen do not apply; however, the Email notification flag must be selected for the order request to Narvar to be generated.
You need to use your account with Narvar to complete configuration, as well as completing the Narvar Integration Setup within Order Management System.
Other email notifications: Only shipment confirmation emails are generated through the Narvar integration. Other email notifications, including return confirmations, follow the standard processes described in the Outbound Email API.
Things to note:
• Items included in the Narvar order message:
• Items that are on the order but still open (that is, not yet shipped, sold out, or canceled), are included in the message with a fulfillment_status of NOT_SHIPPED.
• Items that have been sold out are included with a fulfillment_status of CANCELED.
• Items that have been canceled are included with a fulfillment_status of CANCELED, regardless of whether the cancel reason used was flagged to reduce demand.
• Physical stored value cards: If Use Streamlined Stored Value Card Billing (I23) is selected, then the Narvar order message is generated when you use Working with Physical Stored Value Card Assignment (WPSA); however, no carrier, carrier service, or tracking number is included in the message. However, if Use Streamlined Stored Value Card Billing (I23) is not selected and you confirm physical stored value cards as you do other shipments, then the carrier, carrier service, and tracking information is included.
• Items not included:
• Set master items.
• Non-inventory items, including virtual stored value cards.
• Items added with a negative quantity to process a return.
• Membership items.
• Subscription items.
• Express-billed items.
If the only items on the order fall into one of these categories, then no order message is sent to Narvar.
Drop ship items: When you confirm a drop ship purchase order, either within Order Management System or through integration with Order Broker, then order shipment detail records are not created, and as a result, the carrier, ship method, carrier service, and tracking number are not passed; however, order shipment detail records are created when you confirm a drop ship pick slip.
• If Email notification not selected: The order type must have Email notification selected for the customer to receive the email notification; otherwise, message is generated to the Narvar Non-Deliverable Email Address for Shipment Confirmations (M59). However, in this case, the order transaction history message still indicates Order sent to Narvar.
• Order Broker integration:
• Eligible to be sent to Narvar: The following types of orders are eligible to be sent to Narvar:
• Brokered backorders that originated in Order Management System, submitted to Order Broker as a brokered backorder and fulfilled by a location in another system; however, if the order is assigned back to Order Management System as a fulfilling order, the fulfilling order is not sent to Narvar, as described below.
• Delivery orders that originated in another system and were assigned to Order Management System for fulfillment (that is, not fulfilling orders).
• Retail pickup orders that are not fulfilling orders: Retail pickup orders that are not fulfilling orders for orders originating in Order Management System. These are orders that originated in another system, and that Order Broker sent to Order Management System for fulfillment.
• Ship for pickup orders that originated in Order Management System; however, if the order is assigned back to Order Management System as a fulfilling order, the fulfilling order is not sent to Narvar, as described below.
• Not eligible to be sent to Narvar: The following types of orders are not eligible to be sent to Narvar:
• Fulfilling orders (if Use OROB for Fulfillment Assignment (M31) is selected): When an order originates in Order Management System, was sent to Order Broker for fulfillment assignment, and then Order Broker assigns the order back to Order Management System for fulfillment.
• Store pickup orders.
The generation of order request messages to Narvar is not affected by the setting of the Consolidated Invoice (B49) system control value.
Email repository: Order request messages are not tracked in the Email Repository.
The setup in Order Management System related to the Narvar integration is described below.
Contact Narvar for information on creating and configuring an account.
• Use Narvar Integration (M57)
• Narvar Outbound Service URL (M58)
• Narvar Non-Deliverable Email Address for Shipment Confirmations (M59)
• Narvar Track URL Prefix (M60)
For more information: See the description of each system control value.
Properties: The following properties controlling logging for the Narvar integration:
See the descriptions of these properties under Working with Admin Properties (CPRP) for more information.
Ship via configuration: Complete the following fields to configure mapping a ship via name and service type for Narvar:
The list of valid names and service codes are provided by Narvar.
You must complete the Narvar Carrier Name in order for the tracking number links to work correctly at the Display Package Information Screen, in Streamlined Order Inquiry (DORI), and at the Order Summary page in Contact Center.
Web service authentication: Use the Work with Outbound Web Service Authentication Screen to review or work with web service authentication with Narvar.
Note: Narvar currently supports only Basic authentication.
Order type setting: The order type’s the Email notification flag must be selected for the order request to Narvar to be generated. Also, the Shipment Confirmation must be selected at the Order Type Email Selection Screen for the order type, or the Narvar Non-Deliverable Email Address for Shipment Confirmations (M59) is included rather than the customer’s actual email address.
Logged where? Based on your logging levels, the Narvar request message is logged in the NARVAR.log. See Logs for more information on logging.
Generated when? If Narvar integration is enabled, based on the setting of the Use Narvar Integration (M57) system control value, the message is always generated for a shipment; however, if sending the shipment confirmation is not enabled for the order, the email address specified is the Narvar Non-Deliverable Email Address for Shipment Confirmations (M59). For example, the undeliverable email address is used if the order type does not have Email notification selected, if the customer has opted out of emails, or if the customer’s email address is unknown.
The information mapped in the order_info message to Narvar includes:
order_number: The order number, formatted as 006-330-001, where 006 is the company code, 330 is the order number, and 001 is the ship-to number.
order_date: The order date in YYYY-MM-DDT00:00Z format.
currency_code: The code identifying the currency associated with the source code on the order header. If you do not use multiple currencies, this is the Local Currency Code (A55).
order_items: Summary information for each item on the order, including the following.
• categories: Included only if the item was added to the order as a component of a set. The first set the order is identified as ["CHILD1_SKU"], for example:
"categories":[
"CHILD1_SKU"
],
If there are multiple sets included in the order, each additional set is identified with a sequential number, such as CHILD2_SKU. This code precedes the rest of item information in the message.
The master set item itself is not included in the message; only the component items are included.
• name: The item description.
• sku: The item code, including the SKU, if any. Includes additional spaces to preserve padding for an item code of 12 positions.
• fulfillment_status: Set to:
• SHIPPED if the item has shipped, either previously, or in the shipment that generated the current message.
Note:
• The item is listed here as SHIPPED if a partial quantity has shipped and the line is now closed, even if the full quantity did not ship.
• If a partial quantity of the order line has shipped and a partial quantity has been canceled, the quantity indicated below reflects the shipped, uncanceled quantity.
• The item is still listed as SHIPPED even if it has since been returned.
• NOT_SHIPPED if the full ordered quantity of the item has not yet shipped and the line is still open; for example, if the item is held, backordered, expected to ship from a different warehouse, expected to ship through the integration with Order Broker, or a partial shipment was made.
• CANCELLED if the item has been canceled or sold out:
• This status is passed regardless of how the item was canceled or sold out, including when the order’s Cancel BO flag is selected and a shipment occurs.
• The same status is passed regardless of whether the cancel reason is flagged to reduce demand.
• line_number: A unique number to identify the item on the order. May be different from the order line sequence number if, for example, another item was added to the order and then deleted before entry of this item, or if an item on the order is not included in the message, such as the set master item.
Items not included in the message: Items omitted from the message include set master items, non-inventory items, items added with a negative quantity, membership items, subscription items, and express-billed items.
Ship-alone items: As each unit of a ship-alone item is shipped, it is included in the shipments section of the message, described below.
• item_image: The URL specified for the item image, if any. See Item Image/Info Link Screen for more information.
• item_url: The URL specified for the item Information Link, if any. See Item Image/Info Link Screen for more information.
• unit_price: The actual price of the item on the order. In the case of a set, the set price is included for each component. Any final zeros are truncated from the price; for example, if the price is 12.50, it is passed as 12.5; if the price is 12.00, it is passed as 12.
• quantity: The ordered quantity of the item. May be more than the shipped quantity.
Note: If a partial quantity of the order line has shipped and a partial quantity has been canceled, this quantity is the shipped, uncanceled quantity. For example, if the customer ordered 5 units but only 3 were available, and the 2 backordered units were canceled, the quantity indicated here is 3.
• is_gift: Set to true if the order is flagged as a gift; otherwise, false. Amounts are included in the message regardless of this setting.
billing: Information about the order, including:
• amount: The order total, including merchandise, tax, handling, freight, additional freight, and additional charges, and not limited to the amount billed. Any final zeros are truncated from the amount; for example, if the amount is 122.50, it is passed as 122.5; if the price is 122.00, it is passed as 122.
• shipping_handling: The total freight and handling charges, not limited to the amount billed. Any final zeros are truncated from the freight and handling changes; for example, if the charges is 12.50, it is passed as 12.5; if the price is 12.00, it is passed as 12.
• tax_amount: The total tax amount, not limited to the amount billed. Any final zeros are truncated from the tax amount; for example, if the tax is 12.50, it is passed as 12.5; if the tax is 12.00, it is passed as 12.
• billed_to: Information about the sold-to customer, including:
• email: The sold-to customer’s primary email address, if the customer should receive the shipment notification; see Narvar Non-Deliverable Email Address for Shipment Confirmations (M59) for a discussion.
• phone: The sold-to customer’s:
• Third phone number. If the customer’s third phone number is not defined,
• Day phone number, otherwise,
• Evening phone number.
Phone number formatting is included.
See Phone Numbers (D15) and Third Phone Number Type (L53) for information on mapping and displaying phone number fields.
• address: The customer’s address, including city, state, zip, country code, street1 and street2. The street2 tag includes the second, third, and fourth address lines, if specified. The city, state, and zip tags are always included, but are blank if the customer’s address is unknown or not included, such as for some international addresses.
• first_name: The sold-to customer’s first name. Blank if no first name was specified.
• last_name: The sold-to customer’s last name, or the company name if there is no last name for the customer.
customer: Information about the customer, including:
• address: The sold-to customer’s address, including city, state, zip, country code, street1 and street2. The street2 tag includes the second, third, and fourth address lines, if specified. The city, state, and zip tags are always included, but are blank if the customer’s address is unknown or not included, such as for some international addresses.
• email: The sold-to customer’s primary email address, if the customer should receive the shipment notification; see Narvar Non-Deliverable Email Address for Shipment Confirmations (M59) for a discussion.
• phone: The sold-to customer’s:
• Third phone number. If the customer’s third phone number is not defined,
• Day phone number, otherwise,
• Evening phone number.
Phone number formatting is included.
See Phone Numbers (D15) and Third Phone Number Type (L53) for information on mapping and displaying phone number fields.
• customer_id: The customer number.
• first_name: The sold-to customer’s first name. Blank if no first name was specified.
• last_name: The sold-to customer’s last name, or the company name if there is no last name for the customer.
shipments: Information on each shipment, including the following.
• carrier: The Narvar Carrier Name specified for the ship via. See Working with Ship Via Codes (WVIA). Set to OTHER if you bill by batch (because no tracking number is available), if no Narvar Carrier Name is specified for the ship via, or do not specify the tracking number when you confirm the shipment.
Ship-alone items: Each unit of a ship-alone item is included separately in this section of the message with a quantity of 1.
• items_info: Including:
• sku: The item code, including the SKU, if any. Includes additional spaces to preserve padding for an item code of 12 positions.
• quantity: The quantity shipped.
• ship_method: The description of the ship via. Not included if you bill by batch, or do not specify the tracking number when you confirm the shipment.
• carrier_service: The Narvar Carrier Service Code specified for the ship via. See Working with Ship Via Codes (WVIA). Blank if you bill by batch, if no Narvar Carrier Service Code is specified for the ship via, or do not specify the tracking number when you confirm the shipment.
• ship_date: The shipment date in YYYY-MM-DDT00:00Z format.
• tracking_number: The tracking number specified at shipment. Set to NO TRACKING NUMBER if you bill by batch, or do not specify the tracking number when you confirm the shipment.
• shipped_from: The information about the warehouse or store location that shipped the item, including:
• phone: Phone number formatting is included.
• address: The address of the warehouse or store location, including city, state, zip, country code, street1 and street2.
• company_name: The description of the warehouse or location.
When an order is shipped through the integration with Order Broker, the shipped_from information is from the store cross-reference; see Work with Store Cross Reference (WSCR).
• shipped_to: The shipping address for the order, including:
• email: The sold-to customer’s primary email address, if the customer should receive the shipment notification; see Narvar Non-Deliverable Email Address for Shipment Confirmations (M59) for a discussion.
• phone: From:
• The one-time ship-to, if any; otherwise,
• The sold-to customer’s third phone number. If the customer’s third phone number is not defined,
• The sold-to customer’s day phone number, otherwise,
• The sold-to customer’s evening phone number.
Phone number formatting is included.
See Phone Numbers (D15) and Third Phone Number Type (L53) for information on mapping and displaying phone number fields.
• address: The shipping address, including city, state, zip, country code, street1 and street2. The street2 tag includes the second, third, and fourth address lines, if specified. The city, state, and zip tags are always included, but are blank if the customer’s address is unknown or not included, such as for some international addresses.
• first_name: The ship-to customer’s first name. Blank if no first name was specified.
• last_name: The ship-to customer’s last name, or the company name if there is no last name for the customer.
A sample of the order request message to Narvar is presented below:
"order_info":{
"order_number":"006-330-001",
"order_date":"2020-05-08T00:00Z",
"currency_code":"USD",
"order_items":[
{
"name":"ITEM DESCRIPTION",
"sku":"ITEM SKU",
"fulfillment_status":"NOT_SHIPPED",
"line_number":2,
"item_image":" ",
"item_url":" ",
"unit_price":10,
"quantity":3,
"is_gift":false
},
{
"name":"ITEM DESCRIPTION",
"sku":"ITEM SKU",
"fulfillment_status":"SHIPPED",
"line_number":1,
"item_image":"https://sample.domain.com/images/imageName.png",
"item_url":"https://sample.domain.com/folder/subfolder/ITEM.htm",
"unit_price":10,
"quantity":2,
"is_gift":false
}
],
"billing":{
"amount":58.3,
"shipping_handling":5,
"tax_amount":3.3,
"billed_to":{
"email":"first.last@example.com",
"phone":"(508)555-0111",
"address":{
"city":"WORCESTER",
"state":"MA",
"zip":"01602",
"country":"US",
"street_1":"1234 EXAMPLE STREET",
"street_2":""
},
"first_name":"FIRST",
"last_name":"LAST"
}
},
"customer":{
"address":{
"city":"WORCESTER",
"state":"MA",
"zip":"01602",
"country":"US",
"street_1":"1234 EXAMPLE STREET",
"street_2":""
},
"email":"first.last@example.com",
"phone":"(508)555-0111",
"customer_id":"CSTNBR",
"first_name":"FIRST",
"last_name":"LAST",
"customer_type":"CUSTOMER TYPE"
},
"shipments":[
{
"carrier":"UPS",
"items_info":[
{
"sku":"ITEM SKU",
"quantity":2
}
],
"ship_method":"UPS GROUND",
"carrier_service":"E03",
"ship_date":"2020-05-08T00:00Z",
"tracking_number":"TRACKING NUMBER",
"shipped_from":{
"phone":" ",
"address":{
"city":"WORCESTER",
"state":"MA",
"zip":"01602",
"country":"US",
"street_1":"12345 EXAMPLE AVENUE",
"street_2":"SECOND ADDRESS LINE"
},
"company_name":"WAREHOUSE NAME"
},
"shipped_to":{
"email":"first.last@example.com",
"phone":"(508)555-0111",
"address":{
"city":"WORCESTER",
"state":"MA",
"zip":"01602",
"country":"US",
"street_1":"1234 EXAMPLE STREET",
"street_2":""
},
"first_name":"FIRST",
"last_name":"LAST"
}
}
]
}
}
Trouble with tracking number links:
• Once you enable Narvar and set the Narvar Track URL Prefix (M60), the tracking number links created previously will not work automatically through the Display Package Information Screen in order inquiry, the Tracking number link in Streamlined Order Inquiry (DORI), or the Track Shipments link at the Order Summary page in Contact Center.
• Tracking number links will not work correctly if you do not specify the correct Narvar Carrier Name for the ship via.
Valid tracking number required: If there is no tracking number sent to Narvar, or the tracking number is invalid, then the customer will not receive shipment update notifications from Narvar.
Note: No order shipment detail records are created, and as a result, the carrier, ship method, carrier service, and tracking number are not passed if:
• You bill by batch.
• You do not enter a tracking number,
• You use the Working with Physical Stored Value Card Assignment (WPSA) option for a physical stored value card.
• You confirm a drop ship purchase order, either within Order Management System or through integration with Order Broker; however, order shipment detail records are created when you confirm a drop ship pick slip.
Note: The tracking number specified for a shipment must be unique. Do not attempt to send the same tracking number for multiple shipments on the order.
Tracking number URL: The tracking number URL is stored in the ORDER_SHIPMENT_DETAILS table, composed of the Narvar Track URL Prefix (M60) and the tracking number identified at shipment.
The tracking number consists of https://BASE.URL.com/CARRIER?tracking_numbers=1234&order_number=001-12345-001, where:
• https://BASE.URL.com/ is the Narvar Track URL Prefix (M60).
• CARRIER is the Narvar carrier name specified for the ship via.
• 1234 is the tracking number.
• 001 is the company number.
• 12345 is the order number.
• 001 is the ship-to number.
Required for tracking: The Narvar Track URL Prefix (M60) is required for a valid tracking number link to be enabled in emails or on screens. If you are using the Narvar integration and submit an order request to Narvar while the tracking URL prefix is not defined, the Narvar.log file contains errors such as:
Shipment tracking is disable for company 123
Unable to construct shipment tracking URL for order 456
Where 123 is the company number and 456 is the order number.
Fulfilling orders: The tracking number link is not live for an order that originated in Order Management System, was submitted to Order Broker for assignment, and that Order Broker assigned to Order Management System for fulfillment. See the Use OROB for Fulfillment Assignment (M31) system control value for background on fulfilling orders.
Error displayed: Also, if the tracking URL is not defined, when you click on the tracking number link at the screens mentioned above, an error window indicates: Tracking information not available. Check Narvar Order Error Export screen for failures.
However, a Narvar Order Error Export record is not created because the tracking number link could not be created correctly if there are no other issues with the order request to Narvar.
Working with Narvar Errors: Use the Narvar Order Export Errors page in Modern View to review and work with the errors listed below. The NOEE menu option controls authority to this page.
These errors are stored in the INT_NARVAR_EXPORT_ERROR table.
Country codes: Narvar supports a two-position country code; however, the order request message does not fail if a three-position country code is passed.
Logging: Based on the settings of the NARVAR_LOG_LEVEL property, activity related to the Narvar integration is written to the Narvar.log file.
Extra message? An extra order request message might be sent to Narvar if, for example, the order has shipped, and then an additional express-billed item is added. The express-billed item is not included in the order request message, so the additional message is identical to the previous message and does not affect updates generated by Narvar.
|
Issue |
Narvar.log Entry |
Order Transaction History Message |
Response Type |
Error at Narvar Order Export Errors Page |
|---|---|---|---|---|
|
Narvar Outbound Service URL (M58) is blank |
Shipment Tracking URL or credentials cannot be found |
Failure sending order to Narvar |
0 |
oms.app.exception Application Failure |
|
The order message is not generated because the Narvar Non-Deliverable Email Address for Shipment Confirmations (M59) is blank, and the order is not eligible to have the email actually sent to the customer (see that system control value for more information) |
Missing Narvar Non-Deliverable Email Address |
Failure sending order to Narvar |
0 |
oms.app.exception Application Failure: Missing Narvar Non-Deliverable Email Address |
|
The user ID and password specified for Narvar Service are not valid. See Work with Outbound Web Service Authentication Screen for more information. |
Bad Credentials, Please provide valid acck and auth token. |
Failure sending order to Narvar |
401 |
unauthorized.action Bad Credentials, Please provide valid acck and auth token. |
|
Narvar Outbound Service URL (M58) is invalid |
Shipment tracking order response code 405 and message {"status":"ERROR","messages":[{"level":"ERROR","code":"method.not_allowed","message":"Request method POST not supported"}]} |
Failure sending order to Narvar |
405 |
method.not.allowed Request method POST not supported |
|
The shipment date specified was not formatted correctly. |
message.invalid. order.shipments. date Invalid ship date. Please enter UTC format ’yyyy-MM-dd’T’HH:mm"SSS.zzz’ for ship date |
Failure sending order to Narvar |
422 |
message.invalid.order. shipments.date Invalid ship date. Please enter UTC format ’yyyy-MM-dd’T’HH:mm"SSS.zzz’ for ship date |
Configuration issues: Check your Narvar Integration Setup if you see the following error codes:
• 400: BAD REQUEST
• 403: FORBIDDEN
• 404: NOT FOUND
Other errors: Contact your Oracle representative or Narvar for information on the following error codes:
• 304: NOT MODIFIED
• 409: ITEM ALREADY EXISTS
• 500: INTERNAL SERVER ERROR
• 502: INTERNAL SERVER ERROR
• 503: SERVICE UNAVAILABLE or INTERNAL ERROR
________________________________
Contents SCVs Reports XML Messages Glossary
Copyright © 2021, Oracle and/or its affiliates. All rights reserved.
Legal Notices