Working with Shipments

This section provides an overview of how to work with shipment requests. For an introduction to the concept of shipment requests, see Shipment Requests.

Requesting Shipments

You can use any of the following methods to create shipment requests:

From the Console to ship keys to a single address, see Shipping to a Single Address.
From the Console to ship keys to multiple addresses, see Shipping to Multiple Addresses: Bulk Shipments.
Using the YubiEnterprise API to ship keys to a single address, see API Shipment Requests.

In some cases shipment requests are also manually created by Yubico. After creation, shipment requests are displayed in the All shipments page. Here you can follow shipments, see their status and update information if needed.

Viewing Shipments

To view details for a shipment, go to the Shipments > All shipments page and click the shipment ID in the ID column. To locate a specific shipment, use the search bar at the top or click Filters to filter the list of shipments by one or more fields. You can also sort on all the column headings using different criteria.

Shipments Column Headings

The All shipments page provides the following information:

ID - The ID of the shipment request. Click the ID number to view the shipment details, see Shipment Details View.
Date - Date on which the shipment request was made.
Shipment address - The address to which the shipment was or will be sent.
Recipient email - Email address to which information about the shipment is automatically sent.
Delivery - Type of delivery - “Normal” or “Expedited” (rush).
Type - How the shipping request was created: “MANUAL” (by Yubico), “AUTOMATED” (from Console), or “AUTO FIDO PRE-REG” (FIDO Pre-reg, see Shipping Pre-registered Keys).
Status - The status of the shipment request, see Shipment Statuses.
Address validation override - Indicates whether address validation override has been applied to the shipment (YES/NO).
Tracking - The tracking number with the carrier. Clicking the tracking number takes you to the site of the carrier.
Ship date - Date on which the shipment was dispatched.
Delivery date - Date on which the shipment arrived at its destination.
Reseller - Name of the reseller, if reseller was involved in the purchase.

Filters and Table Controls

You can modify the appearance of the table and the data displayed using the controls at the top of the page.

Columns - Determine which columns will be shown in the table. Click Columns and select or deselect the desired columns. Click Reset to return to a previous selection. You can also drag and drop the columns to place them in a desired order on the page.
Filters - Filter data to be displayed. Click Filters, select an Operator and a Value, and click Apply. Available filter fields depend on the data in the table of the Console page you are working with. Click Clear all to remove the selected filters.
Density - Determine the space between rows in the table, for example “Compact”.

Searching Shipments

To locate a specific shipment, you can use the search field or filter the list of shipments by one or more fields. You can also perform advanced searches by combining search with filters to drill down further into the list of shipments.

The Search field at the top of the All shipments page lets you locate any element in a shipping request, even partial words or numbers. Entering search parameters instantly filters the list of shipments based on those parameters. Change or remove the search parameters in the Search field to reset the search.

Note

Using the search bar will search on shipment ID, External order ID, Recipient email, and Tracking number fields. To search on other fields, click Filters.

To return to viewing the list of search results after clicking into one of the list items, click Go back. The list remains available even after refreshing the browser window while on a page of search results.

Shipment Request Status

The shipment request Status shows the progress of the shipment request, for example “Awaiting Validation”, “Delivered”, or “Incomplete”. For more information, see Shipment Statuses.

In case of shipment request errors, click the shipment ID to open the Shipment details view to investigate the shipment information. To edit a shipment request and correct errors, see Editing or Deleting Shipments.

Shipment Details View

To open the Shipment details view, click the shipment ID either from the ID column on the Shipments page, or in the Recent Shipments section of the Dashboard.

The Shipment details page displays the following information:

SHIPMENT ID section - The shipment ID and type of shipment request (manual/automated).
- REQUEST DATE and REQUESTOR - The date when the shipment request was created, and the email of the user who created the shipment request.
- RESELLER NAME and ID - Name and ID of the reseller.
SHIPMENT STATUS section - Status and related status messages for the shipment request.
Address section - Contact information for the shipping recipient.
Shipping section - Details about type of delivery, shipping provider and tracking number, if available.
Costs section:
- Product cost - The total cost of purchased products included in the shipping.
- Product tax/VAT - The product tax/VAT based on the total product cost.
- Shipping Fee - The shipping cost based on included products and shipping destinations.
- Shipping tax/VAT - The shipping tax/VAT based on the shipping cost.
- Total - Total cost including shipping and taxes. See shipping costs.
Item details section:
- Inventory product type - Type of inventory, for example “Compliance - Plus- Primary”, see Tier Options.
- Product name - Type of product, key model.
- Customization ID/Customization label - Unique ID and its friendly name representing a specific type of key customization, see Customizations. The columns are only visible if a shipment contains items from a customized inventory.
- PO reference - The purchase order associated with the shipment request.
- Quantity - The number of keys included in the selected shipment.
- Cost per item - The cost for each product of a certain type included in the shipment.
- Cost - The total cost for the shipment.
- Action - Lets you view information associated with a specific shipment of customized keys, see Viewing Customization Details. The column is only visible if a shipment contains items from a customized inventory.

If the shipment request has not yet been locked for processing and fulfillment, you can edit the recipient information and product selection. For more information, see Editing or Deleting Shipments.

Editing or Deleting Shipments

You can update an address or delete a shipment request until it is locked for processing and fulfillment, see Time Frames. This applies for both Automated and Manual type of requests. However, to edit or delete a Manual shipment request, you must contact Yubico to update the shipment request.

Note

You can edit shipments of type Auto FIDO Pre-reg (pre-registered keys) in the same states as for other automated shipments. You can update the recipient and address information, and change the delivery type. However, you cannot change the products included in the shipment.

To edit or delete a shipment request, do the following:

Click Shipments > All shipments in the left menu to open the All shipments page.
Click the Edit icon for the desired item in the table to open the Shipment details page.
To update the information, scroll down to the Edit Shipment section. You can for example edit the recipient and shipping information, or update the delivery type if needed.

Important

To avoid delivery issues to addresses with long street names, for all shipments to India the maximum combined character limit is 120 characters between Address line 1 and 2. For shipments to other destinations the combined address line character limit is 105. For more information, see Recipient Information.

To make changes in the product selection, go to the Product Selection section. Note that Shippable Inventory limits might apply.

If you are confident that the provided address is valid for a shipment where the address validation failed, you can select Opt out of address validation to override the system address validation. For more information, see Overriding Address Validation.

Important

If you chose to override the Yubico validation service and a shipment is returned or otherwise undeliverable, Yubico will not refund the product, shipping fees, applicable taxes and/or VAT associated with that shipment.
Make the required changes, click Update, then click Confirm to confirm your changes. The update function validates the fields, with a warning on any fields requiring input. To delete the shipment, click Delete shipment and confirm the deletion. To delete multiple shipments at the same time, see Deleting Multiple Shipments.

Reviewing Incompletes

The address validation service flags addresses that are problematic or incorrect and displays this information in the Status column on the All shipments page. To ensure your shipping request is accepted and processed, always verify that it has not been flagged as incomplete or with failed address validation. For explanation of different statuses, see Shipment Statuses.

To review and manage incomplete and failed shipment requests, do the following:

In the All shipments page, click Filters and for the Status filter, select the applicable status in the list, for example Address Validation Failed or Incomplete Shipping Request. Then click Apply to filter out the shipments.
Open the Shipment details page for each shipment and view the information under MESSAGES In the SHIPMENT STATUS section to understand what is incorrect in the shipment information. For example, parts of the address might be missing or is entered incorrectly. Or, shipping of the requested product set is not allowed for the destination country.
Update the information as described in Editing or Deleting Shipments.

Deleting Multiple Shipments

To delete multiple shipment requests at the same time, do the following:

Click Shipments > All shipments in the left menu.
In the All shipments page, select the checkbox to the left on the row for each shipment you want to delete. Only shipments with the appropriate status can be selected. For example, a shipment with status “Shipped: In transit” cannot be selected for deletion.

You can use filters to filter out shipments with a status making them available for deletion. Click Filters and Can be deleted, then click Apply.

To select all rows in the table, select the checkbox in the header. To clear a selection of rows, select the checkbox in the header again.
When satisfied with your selection, click Delete in the bar at the bottom and click Confirm in the Confirm deletion dialog.

Overriding Address Validation

The Yubico address validation service sometimes gives an error even if an address is valid. As a Console Owner or Console Admin you can override the Yubico validation warnings if you are confident that a provided address is valid. You can override the address validation for existing shipment requests with status “Address Validation Failed”. You can also choose to override the address validation when creating shipment requests.

Important

If you chose to override the Yubico validation service and a shipment is returned or otherwise undeliverable, Yubico will not refund the product, shipping fees, applicable taxes and/or VAT associated with that shipment.

To override address validation for a single existing shipments, do the following:

Locate the desired shipment, either in the All shipments page or the Review incompletes page.
Click the ID for the shipment to open the Shipment details page. Alternatively, click the Edit icon for the shipment in the Status column.
In the SHIPMENT STATUS section of the Shipment details page, click Override address validation.
Click Confirm in the Confirm address validation override dialog.

To override address validation for multiple existing shipments, do the following:

Click Shipments > All shipments in the left menu.
In the All shipments page, select the checkbox for each shipment with status “Address Validation Failed” for which you want to apply address validation override.

Only shipments with the appropriate status can be selected. To filter out shipments with appropriate status, click the Can override address validation option under Filters. To select all rows in the table, select the checkbox in the header. To clear a selection of rows, select the checkbox in the header again.
Click Override address validation in the bar at the bottom and click Confirm.

To override the address validation when creating new shipment requests, select the Override address validation option when creating the shipment request. For more information on how to create shipment requests, see Shipping to a Single Address and Shipping to Multiple Addresses: Bulk Shipments.

Note

If address validation override is applied to a shipment, you can still update the address for that shipment. In this case, the address validation override will also be applied to the updated address. If you do not want address validation override to apply to the updated address, deselect the Override address validation option when editing the address. For more information, see Editing or Deleting Shipments.

Downloading List of Shipments

Console Owners, Admins, and Auditors can download a list of shipment requests that have been made. This can be useful if you want to perform data analysis for example to identify address validation failures for specific shipping destinations. You can then filter out shipments with status “Address Validation Failed” and download a file with those specific shipments.

To download a CSV file with general shipment data, go to the Shipments > All shipments page and click Download CSV in the top row.

When downloading the CSV file, only enabled columns and filtered rows are included. Use the Search field or click Filters to filter out desired shipments. Click Columns to include desired columns in the output. For more information, see Filters and Table Controls.

Note

If no filtering is applied, data for ALL shipments in the table will be included in the CSV file. Ensure to filter out desired shipments before downloading to only get the data you are interested in. If your selection contains a large number of rows, generation of the download CSV file might take some time to complete.

Column Headings in Download File

The All shipments table downloaded as a CSV file combines shipment details information with what is shown on the All shipments page, plus some additional information. The column headings are described below.

Note

Although all currency amounts displayed by the system are in US dollars, contracts, purchase orders, and invoices, etc. use the currency applicable to the parties involved.

shipment_id - Unique identifier assigned by YubiEnterprise Delivery to every shipment request.
shipment_request_date - Month/day/year.
shipment_update_date - Month/day/year.
organization_name - Name of the customer organization on behalf of which the shipment request was made (typically the same throughout the file).
reseller_id - Identifier of the reseller (Yubico’s channel partner) - this is “1” if it was a direct sale by Yubico.
user_email - The email address of the YubiEnterprise Delivery user who made the shipment request.
country_code_2 - Two-letter country code. For more information, see Shipping to Multiple Addresses: Bulk Shipments.
inventory_type - Depends on items entered in the PO, for example “Standard Inventory Keys”.
is_delivered - TRUE or FALSE.
is_shipped - TRUE or FALSE.
shipped date - Month/day/year - date of shipping.
delivered_date - Month/day/year - date of delivery.
tracking_number - Tracking number assigned by fulfillment agency.
recipient_company - Name of recipient’s company.
recipient_email - Recipient’s email address.
recipient_firstname - First name of recipient.
recipient_lastname - Last name of recipient.
recipient_telephone - Recipient’s telephone number.
street_line1 - First line of street address.
street_line2 - Second line of street address.
street_line3 - Third line of street address (deprecated).
city - Name of village, town, or city.
region - Name or region, state, or province.
postal_code Postal code, post code, zip code.
bypassed_address_validation - Indicates whether the Yubico address validation service has been overridden (TRUE or FALSE), see Overriding Address Validation.
shipment_type - “Automated” (entered into the YubiEnterprise system by customer), “Manual” (entered into the system by Yubico), or “Fido2PreRegistered” for FIDO Pre-reg shipments.
delivery_type Normal or Expedited.
shipment_state_code - see Shipment Status Codes.
shipment_state_id - see Shipment Status Codes.
shipment_state_message - see Shipment Status Codes.
shipment_summary_description - Total number of keys plus number of each type, for example Total Keys: 2 yk5c:1, sky2:1 means two keys were shipped, one a YubiKey 5C and one a Security Key 2.
shipment_product_cost - Cost of product alone, without tax, VAT, or shipping.
shipment_product_taxes - Cell is populated if products are shipped to location where sales tax is applicable. Amount of sales tax levied on product.
shipment_product_vat - Cell is populated if products are shipped to location where VAT is applicable. Amount of VAT levied on product.
shipping_service_cost - Cost of shipping.
shipping_service_taxes - Cell is populated if products are shipped to location where sales tax is applicable. Amount of sales tax levied on shipping.
shipping_service_vat - Cell is populated if products are shipped to location where VAT is applicable. Amount of VAT levied on shipping.
total_shipment_product_cost - Cost of product(s) with tax or VAT; does not include shipping costs or tax or VAT on them.
total_shipment_tax_cost - Cell is populated if products are shipped to location where sales tax is applicable. Total sales taxes levied on product(s) plus shipping costs.
total_shipping_service_cost - Total shipping costs including taxes or VAT levied on them
total_keys_shipped - Total number of products shipped.
purchaseorder_numbers - If multiple POs were drawn on for a single request, they are separated by a pipe, for example PQR_123|PO-0721a.
reseller_name - Name of the reseller from whom you purchased, Yubico’s channel partner, based on the reseller_id column.

Note

For FIDO Pre-reg type of shipments, the CSV file will also include serial number and firmware version for each custom key. The information is included after the shipment has been processed by Yubico Fulfillment Center, and the shipment is moved to state “Shipped: in Transit”.

Notifying About Shipments

The YubiEnterprise Delivery system automatically notifies shipment recipients by email:

When products are sent to them - using the SHIPPED template below.
When products are delivered - using the DELIVERED template below.
If there is a problem with the delivery - using the DELIVERY EXCEPTIONS template below.

The relevant email notification will be sent to the email address provided when the order was placed.

SHIPPED

Subject: YubiKeys shipped!
To: <Email address of recipient provided in shipping request>

Hello, <Name of recipient, or if absent, company name>
Your YubiKeys have been shipped. If you have any questions,
please reach out to your company administrator.

<Custom text, if any>

YubiKeys Shipped:
<Type of YubiKey> <Quantity>
Delivered To: <Name and address of recipient>
<Name of Carrier> Tracking Number: <TrackingNumber>

Sincerely,
Your YubiEnterprise Delivery Service Team
This is an automatically generated message from Yubico.
Replies are not monitored or answered.

DELIVERED

Subject: YubiKeys Delivered!
To: <Email address of recipient provided in shipping request>

Hello, <Name of recipient, or if absent, company name>
Your YubiKeys have been delivered. If you have any questions,
please reach out to your company administrator.

<Custom text, if any>

YubiKeys Delivered:
<Type of YubiKey> <Quantity>
Delivered To: <Name and address of recipient>
<Name of Carrier> Tracking Number: <TrackingNumber>

Sincerely,
Your YubiEnterprise Delivery Service Team
This is an automatically generated message from Yubico.
Replies are not monitored or answered.

DELIVERY EXCEPTIONS

Subject: YubiKeys Delivery Exceptions!
To: <Email address of end-user, intended recipient>

Hello <Name of end-user>

Your Shipment request for YubiKeys has delivery exceptions.
Please reach out to your company administrator. You can also
reach out to us at YubiEnterprise Support
<https://www.yubico.com/products/yubienterprise/contact-support/>

<Custom text, if any>

Delivery Details:
<Type of YubiKey> <Quantity>

Deliver To:
<Address of intended recipient>
<Name of Carrier> Tracking Number: <TrackingNumber>

<Error text>

Sincerely,
Your YubiEnterprise Delivery Service Team

This is an automatically generated message from Yubico.
Replies are not monitored or answered.

Customizing Automated Emails

You can customize the automated templates as desired to adapt the message for your specific organization. You can change the look and feel of the email as well as the text, for example to add a link to your own support organization, or contact information for your own IT department.

The templates accept any valid HTML, including scripts. Web and email links can be inserted as HTML link elements. Put the link target in the href attribute, and put the display text for the link between the angle brackets. For example:

Please visit <a href="https://yubico.com">Yubico's webpage</a> for more information, or
email <a href="mailto:someone@yourcompany.com">someone@yourcompany.com</a>.

To replace the Yubico logo image at the top of the email page, replace the existing image link with one of your choice, for example your company logo. Ensure that the image you use is stored in a publicly available space.

<img alt="yubico" width="168" height="50" src="https://console.yubico.com/media/yubico_logo.png">

The following values in the template can be used anywhere in the email body and will be substituted when the email is sent:

{{.Name}} - the first and last name of the recipient.

{{nl2br .Address}} - the destination address.

{{.Carrier}} - the carrier used, for example UPS, FedEx or USPS.

{{.TrackingNumber}} - tracking number of the shipment.

{{.CopyrightYear}} - the current year.

{{.Email}} - recipient email address.

The following code lists quantity and items in the shipment:
{{range $name, $qty := .LineItems}}
{{$name}}: {{$qty}}
{{end}}

To customize notification emails, do the following:

In the Console, click Settings > Email and select the Template to be customized: Shipped, Delivered, or Delivery Exceptions.
Insert the desired content into the template.
Your HTML code is validated as you type. If your code is correct, a green banner appears, and you can continue editing or click Update. A red banner appears if the HTML is incorrect. Correct it and click Update, or click Restore. Once you click Update, the Restore button is deactivated.
To view the customized email you created, click Send sample.

Note

If you make a mistake in the HTML code when customizing the template, you can click the Restore button to return to the default. However, if your HTML is correct and you click Update, you can no longer click Restore. For this reason, consider making a copy of the default template before you customize it.

Viewing Processed Refunds

When shipments fail to arrive at their destination, the price of product(s) plus shipping is refunded. The status of such a shipment is recorded as “Lost/Missing”. Console Owners, Admins, and Auditors can access refund details.

Click Shipments > Processed refunds in the left menu to display the Processed refunds page.

The Processed refunds table shows the following information:

Shipment ID
Inventory product type (shipping, subscription type, etc.)
PO reference if applicable (link to PO from which the refunded inventory was drawn)
Refund quantity (this value will be “0” for shipping)
Product name
Refund date
Refunded amount

To see more details, click the Shipment ID of the desired shipment to view its details. For more information, see Shipment Details View. Fore more information about refunds, you can also download a file.

If your organization is shipping custom keys, the Customization ID and Customization label (user-friendly name) associated with a refunded shipment are displayed in the Shipment details page. For more information, see Customizations.

Downloading List of Refunds

To download a CSV file listing all the data shown on the list of processed refunds, click Download refund CSV in the upper right of the Processed refunds page.

The download file contains the following information for each refunded shipment request:

shipment_id
refund_date
organization_name
reseller_name
reseller_id
inventory_product_type
product_name
refund_quantity
product_cost
refunded_product_tax
refunded_product_vat
refunded_shipping_fee
refunded_shipping_tax
refunded_shipping_vat
purchaseorder_number
country_code_2
shipment_request_date
shipped_date
recipient_company
recipient_email
recipient_firstname
recipient_lastname
recipient_telephone
street_line1
street_line2
street_line3
city
region
postal_code

To file a support ticket for YubiEnterprise Delivery, click Support.