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:

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.

_images/shipments-overview2.png

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.

Modifying the Table View

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

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.

To locate a specific shipment, you can perform advanced searches by combining search with Filters to drill down further into the list of shipments.

Example: You want to locate the tracking number for a shipment with status “Address Validation Failed” to your London office and a recipient with a name containing “John”. In the Search field, enter “London”. Then apply a filter where First name contains “John” and where Status is “Address Validation Failed”, and click Apply. The tracking number is displayed in the Tracking column.

You can also use advanced search to find shipping information for customized YubiKeys where you know the serial number and/or the firmware version.

Example: To find out the delivery status for a shipment of a customized YubiKey with the serial number “123456789”, apply a filter where Serial number equals “123456789”, and click Apply.

To return to viewing the list of search results after clicking a list item, click Go back. The list remains available even after refreshing the browser window while on a page of search results. To remove all filters, click Clear all.

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.

_images/shipment-details-one.png _images/shipment-details-two1.png

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:

  1. Click Shipments > All shipments in the left menu to open the All shipments page.

  2. Click the Edit icon for the desired item in the table to open the Shipment details page.

  3. 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.

  4. 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:

  1. 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.
  2. 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.
  3. 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:

  1. Click Shipments > All shipments in the left menu.

  2. 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.

    _images/shipment-delete-filter3.png

    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.

    _images/shipment-bulk-deletion1.png

  3. 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:

  1. Locate the desired shipment, either in the All shipments page or the Review incompletes page.

  2. Click the ID for the shipment to open the Shipment details page. Alternatively, click the Edit icon for the shipment in the Status column.

  3. In the SHIPMENT STATUS section of the Shipment details page, click Override address validation.

    _images/override-address-valid-button.png

  4. Click Confirm in the Confirm address validation override dialog.

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

  1. Click Shipments > All shipments in the left menu.

  2. 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.

  3. 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 Modifying the Table View.

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”.

Resolving Shipment Issues

The following describes the different statuses a shipment can have and how to resolve issues that might occur.

Notifications regarding shipment issues are displayed in the Console as well as sent by email to relevant recipients. You can view the status for a shipment in the Status column of the All shipments page. You can also filter out shipments based on their status using the advanced search.

For explanations of shipment error messages in the API, see Shipment Error Messages.

Shipment Statuses

  • Accepted for Fulfillment

    Explanation: Shipment request address has been validated and is ready to be picked up for fulfillment processing.

    Action: Information only, no action needed.

  • Address Not Accepted by Carrier

    Explanation: The shipment request was not accepted due to the recipient address exceeding the maximum character length set by the carrier.

    Action: Update shipment request, if possible shorten the address information.

  • Address Validation Failed

    Explanation: The Yubico address validation service failed because the address provided is not sufficient to guarantee delivery. The correct address must be provided before proceeding. No keys, tax, or shipping credits have been deducted from inventory. For more information, see Reviewing Incompletes.

    Action: Check address in shipment request.

  • Awaiting Validation

    Explanation: The shipment request has been received, no validation done yet.

    Action: Information only, no action needed.

  • Awaiting DPL Confirmation

    Explanation: The shipment is being reviewed for DPL match, see “Error: DPL Match”.

    Action: Check shipment status, if updated to “DPL Confirmation” the shipment will not be processed.

  • Cancelled

    Explanation: The shipment has been cancelled, for example because a fulfillment partner was not able to ship the order.

    Action: Contact Yubico Support for information.

  • DPL Confirmed

    Explanation: The shipment was automatically detected as a DPL match (see “Error: DPL Match”), and has been reviewed by Yubico and found to be a confirmed match (not false positive). The shipment will not be processed.

    Action: Check shipment request, create alternative shipment request if applicable.

  • Delivered

    Explanation: The shipment was delivered to the recipient.

    Action: Information only, no action needed.

    Note

    The Console lists the status of some shipments as “Delivered” when the tracking service shows “Delivered to Sender” (meaning the shipment was returned to sender).

  • Delivery Exception

    Explanation: The shipment request was processed and shipped successfully, but the delivery was unsuccessful. The order is now the responsibility of the fulfillment partner.

    A “Delivery Exception” is triggered when a carrier is citing an order delivery issue. Common reasons for delivery exceptions are undeliverable address, missing door code or telephone number, company name on a residential address, delivery delays, and items held at customs.

    Action: Check shipment request tracking information, contact carrier.

  • Error: DPL Match

    Explanation: The shipment recipient has been found on the Bureau of Industry and Security’s denied persons list (DPL). All individuals and entities on the DPL are prohibited from participating in export transactions. The DPL match is awaiting review and confirmation by Yubico.

    Action: Check shipment status, if updated to “DPL Confirmation” the shipment will not be processed.

  • Error: Processing Error, contact Support

    Explanation: The system encountered an issue processing inventory and financial debits. The error was likely caused by insufficient key or credit inventory. The shipment request will either need to be edited to reflect available inventory, or sufficient inventory must be added through a new PO. The shipment will not be sent to the fulfillment partner again until it has been reprocessed.

    Action: Check inventory, contact Yubico Support to add more if needed.

  • Error: Shipping Error, contact Support

    Explanation: The system encountered an issue when sending the shipment request to the fulfillment partner. The shipment request must be reprocessed before sending it to the fulfillment partner again.

    Action: Contact Yubico Support to resolve issue.

  • Incomplete

    Explanation: The address provided is incomplete. The correct address must be provided before proceeding. No keys, tax, or shipping credits have been deducted from inventory. For more information, see Reviewing Incompletes.

    Action: Check address in shipment request.

  • Incomplete Shipping Request

    Explanation: The shipment request contained data that the system could not understand or parse. The request must be corrected before proceeding. No keys, tax, or shipping credits have been deducted from inventory. For more information, see Reviewing Incompletes.

    Action: Check shipment request input data.

  • Manual Processing

    Explanation: Shipment is being fulfilled manually.

    Action: Information only, no action needed.

  • Processing: Queued for Fulfillment

    Explanation: Shipment is being fulfilled manually. No further action is required by the shipment requestor.

    Action: Information only, no action needed.

  • Processing: Ready for Fulfillment

    Explanation: Shipment is being fulfilled manually. No further action is required by the shipment requestor.

    Action: Information only, no action needed.

  • Processing: Sent for Fulfillment

    Explanation: Applies to automated shipments only. The shipment request was sent to the fulfillment partner via the API for processing.

    Action: Information only, no action needed.

  • Requested

    Explanation: Applies to manual shipments only. The inventory has been deducted from the associated account, and the order is being prepared by the Yubico fulfillment team.

    Action: Information only, no action needed.

  • Returned to Sender

    Explanation: The shipment has been returned to the sender by the carrier.

    Action: Contact Yubico Support for information.

  • Shipment Lost/Missing

    Explanation: The shipment was lost in transit to the recipient.

    Action: Contact Yubico Support for replacement (unless address validation override was applied).

  • Shipped: In transit

    Explanation: The shipment request was released to and shipped by the fulfillment partner and billed by Yubico.

    Action: Information only, no action needed.

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.

_images/processed-refunds-view1.png

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

Customizing Automated Emails

The YubiEnterprise Delivery system automatically sends notifications related to various statuses for shipment requests, for example shipments that failed and require user interaction. Notifications regarding shipments are displayed in the Console as well as sent by email to relevant recipients.

The automated shipment notifications sent by email are based on pre-defined templates. You can customize these templates as desired to adapt the message for your 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 following email templates are available:

  • Delivered - notify recipients that products are delivered.
  • Delivery Exceptions - notify recipients that there is a problem with a delivery.
  • Shipped - notify recipients that products have been sent to them.
  • Tracking Update - notify recipients that tracking information for a shipment has changed.

To see the content of an email template, click Settings > Email in the Console left menu, and select the desired template in the Template dropdown.

The email 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:

  1. In the Console left menu, click Settings > Email, and in the Template dropdown, select the template you want to customize.

    _images/send-sample-custom-email1.png

  2. Insert the desired content into the template.

  3. 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.

  4. 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.

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