Bulk Upload: Shipping to Multiple Addresses

The information in Requesting Shipment: Introduction applies to this method.

Note

Although Console users can specify the inventory they want to draw from for individual shipment requests, this option is not available for bulk shipments. Bulk shipment requests for Subscription (1.0) allow only the selection of initial, replacement, or buffer stock. When inventory is not specified or cannot be specified, the system uses the “first in, first out” rule, which means it will deduct from the oldest purchase order first.

Template

To create a bulk request in the form of a CSV file, use the shipment spreadsheet template supplied by the Console, bulk_shipment_template.csv. Each row - i.e., each individual shipping request - is processed independently, so that issues with one request do not hold up other requests.

Always download the latest version of the template. The template is autogenerated based on your inventory. When a new CSV template becomes available, the outdated version of the template no longer produces valid shipping requests. The CSV template changes frequently; for example, when:

  • Yubico releases new products in tiers to which your organization is subscribed. Therefore, new fields are added to the template to take account of them.
  • We release a new version of the YubiEnterprise Delivery software that includes updates to the template such as columns for additional information.
  • You add new products to your inventory through a new PO. Subscription customers have columns for each of the keys in their subscription tier(s).

The CSV bulk upload does not support combining subscription and non-subscription products in a single shipment. If you want to create a shipment request that includes both types of products within a single shipment, see Shipping Request Via API or Shipping to a Single Address (Console).

Ensure that:

  • The columns of your own CSV file correspond exactly to those in the CSV template.
  • The header row from the template is included in your own CSV file.
  • The contents of the cells do not exceed the limits. The columns with table cells that have limits on the number of alpha-numeric characters (including spaces) are listed in Shipment Request Fields below. Not all columns have limits. Note that the only products listed in your bulk_shipment_template.csv are those your organization has purchased, whereas the table in Shipment Request Fields lists all products.

Post Office Boxes

Although the system can deliver to Post Office (PO) Boxes within the United States, delivery to the equivalent elsewhere in the world is unlikely to succeed.

Shipping Label Content

First Line

In the Console, First name and Last name and in the CSV file, recipient_firstname and recipient_lastname map to the first line on the shipping label.

Long recipient names can be problematic for all methods of requesting shipment, because the shipment request will fail if the contents of the First name / Last name fields and/or Company or recipient fields exceed the maximum number of characters permitted in these fields (shown in the table below). Workaround: When a recipient’s full name or company name exceeds the fields’ maximum lengths, split the names across the three fields, for example:

Location Field (limit=15) Limit Field (limit=20) Limit Field (limit=20) Limit
API recipient_firstname 15 recipient_lastname 20 recipient 20
CSV recipient_firstname 15 recipient_lastname 20 recipient_company 20
Console First name 15 Last name 20 Company 20
Example of an overly long name before adjustment to fit the fields
  Johannes-Maximilian   von Derschowitz-Dampfloch zu Querdenker
Example after adjustment
  Joh.-Maximilian   v.DerschowitzDampfloch   zu Querdenker  

Second Line

The Company field in the Console, the recipient field in the API and the recipient_company column in the CSV require the name of the recipient’s company if the address is not a residential one. This maps to the second line on the shipping label.

_images/corporate-address.png

Note

API: Do not use the /shipments recipient field to specify the name of the individual to whom products are to be shipped. For this, use the recipient_firstname and recipient_last name fields instead.

If the address is residential, leave empty:

  • The Company field in the Console
  • The recipient_company cell in the CSV file
  • The recipient field in the API.
Examples of Bad Usage of Company Name Field

For example, entering the following information for a shipment request would result in failure because USPS recognizes that there are multiple companies in the building whose address is 530 Lytton Avenue:

Jan Lindberg
530 Lytton Avenue
Palo Alto, CA 94301
USA

Similarly, entering the following information for a shipment request would result in failure because a residential address would not be associated with a company.

Jan Lindberg
Yubico Inc.
6 Lea Rd
Dronfield S18 1SB
UK

Inventory Sources

The entity through which you submit a PO is always referred to as a channel partner, even if it was a direct purchase. Yubico’s Channel partner ID (or ChannelPartnerId or channelpartner_id) is “1”.

Note

The selection of channel partner is not supported in the /shipments API.

Because inventory is sorted according to the source from which it was purchased, when requesting shipment, distinguish between inventory purchased directly from Yubico and inventory purchased from Yubico’s channel partners. The Dashboard shows your total inventory of any given product, combining quantities purchased from all sources: both directly from Yubico and indirectly through channel partners. To find out what is in which inventory, check your purchase orders.

To find out what the channel partner ID is:

BEFORE shipment:
 

The name of the channel partner are shown on the Purchase orders tab, and the channel partner ID is shown on the PO detail popup accessed by clicking on the Purchase order number:

_images/po-detail-1000-50-250.png
AFTER shipment:

The Channel partner ID is shown on the shipment request detail page, accessible by clicking the ID of the shipment request on the Shipments tab.

_images/ship-req-detail.png

Note

You have an inventory from each channel partner. To request shipment from two or more inventories, make a shipment request for each inventory. For example, to have three YubiKey 5C NFC delivered to Jan Lindberg, even if your dashboard shows that you have three such keys, if one of those keys was purchased from Yubico, the second from channel partner A and the third key from channel partner B, you need to make three shipment requests, each one of them drawing on a different inventory.

Procedure for Bulk Uploads

Step 1:

Click Create shipment request. The New shipping request popup appears.

Step 2:

From the Bulk Shipment tab of the New shipping request popup, click Download shipment spreadsheet template (csv), the name of which is bulk_shipment_template.csv.

Do not confuse this button with the Download CSV button next to the Shipment request button on the Shipments tab.

Step 3:

Get the country codes required for populating this file: still on the Bulk Shipment tab of the New shipping request popup, click Download available countries (csv).

Step 4:

Save the CSV file preparatory to populating it with your information. The only purpose of the filename is to enable you to identify it correctly when you upload it. The following steps call out only certain fields. Shipment Request Field Limitations below covers all the fields.

Step 5:

In the InventoryType column, use the values from the table below:

Product <> Inventory Type Mapping
Product or Inventory Name shown on Purchase Order Value to use for inventory_type
YubiKey Lanyard 1
Security Key C NFC by Yubico (Black) 1
Security Key C NFC by Yubico - Enterprise Edition 1
Security Key NFC by Yubico (Black) 1
Security Key NFC by Yubico - Enterprise Edition 1
YubiKey 5 Nano 1
YubiKey 5 Nano FIPS 1
YubiKey 5 NFC 1
YubiKey 5 NFC FIPS 1
YubiKey 5C 1
YubiKey 5C FIPS 1
YubiKey 5C Nano 1
YubiKey 5C Nano FIPS 1
YubiKey 5C NFC 1
YubiKey 5C NFC FIPS 1
YubiKey 5Ci 1
YubiKey 5Ci FIPS 1
YubiKey Bio - FIDO Edition 1
YubiKey C Bio - FIDO Edition 1
Advanced - Plus - Backup 3
Advanced - Plus - Backup - Replacement 5
Advanced - Plus - Primary 3
Advanced - Plus - Primary - Replacement 5
Advanced - Standard - Backup 3
Advanced - Standard - Backup - Replacement 5
Advanced - Standard - Primary 3
Advanced - Standard - Primary - Replacement 5
Advanced/Bio - Plus - Backup 3
Advanced/Bio - Plus - Backup - Replacement 5
Advanced/Bio - Plus - Primary 3
Advanced/Bio - Plus - Primary - Replacement 5
Advanced/Bio - Standard - Backup 3
Advanced/Bio - Standard - Backup - Replacement 5
Advanced/Bio - Standard - Primary 3
Advanced/Bio - Standard - Primary - Replacement 5
Backup Subscr - Adv. Tier: Buffer 4
Backup Subscr - Adv. Tier: Initial 3
Backup Subscr - Adv. Tier: Replacement 5
Backup Subscr - Base Tier: Buffer 4
Backup Subscr - Base Tier: Initial 3
Backup Subscr - Base Tier: Replacement 5
Backup Subscr - FIPS Tier: Buffer 4
Backup Subscr - FIPS Tier: Initial 3
Backup Subscr - FIPS Tier: Replacement 5
Backup Subscr - Prem. Tier: Buffer 4
Backup Subscr - Prem. Tier: Initial 3
Backup Subscr - Prem. Tier: Replacement 5
Base - Plus - Backup 3
Base - Plus - Backup - Replacement 5
Base - Plus - Primary 3
Base - Plus - Primary - Replacement 5
Base - Standard - Backup 3
Base - Standard - Backup - Replacement 5
Base - Standard - Primary 3
Base - Standard - Primary - Replacement 5
Base/Bio - Plus - Backup 3
Base/Bio - Plus - Backup - Replacement 5
Base/Bio - Plus - Primary 3
Base/Bio - Plus - Primary - Replacement 5
Base/Bio - Standard - Backup 3
Base/Bio - Standard - Backup - Replacement 5
Base/Bio - Standard - Primary 3
Base/Bio - Standard - Primary - Replacement 5
Compliance - Plus - Backup 3
Compliance - Plus - Backup - Replacement 5
Compliance - Plus - Primary 3
Compliance - Plus - Primary - Replacement 5
Compliance - Standard - Backup 3
Compliance - Standard - Backup - Replacement 5
Compliance - Standard - Primary 3
Compliance - Standard - Primary - Replacement 5
Non-subscription - Advanced Tier 2
Non-subscription - Base Tier 2
Non-subscription - FIPS Tier 2
Non-subscription - Premium Tier 2
Primary Subscr - Adv. Tier: Buffer 4
Primary Subscr - Adv. Tier: Initial 3
Primary Subscr - Adv. Tier: Replacement 5
Primary Subscr - Base Tier: Buffer 4
Primary Subscr - Base Tier: Initial 3
Primary Subscr - Base Tier: Replacement 5
Primary Subscr - FIPS Tier: Buffer 4
Primary Subscr - FIPS Tier: Initial 3
Primary Subscr - FIPS Tier: Replacement 5
Primary Subscr - Prem. Tier: Buffer 4
Primary Subscr - Prem. Tier: Initial 3
Primary Subscr - Prem. Tier: Replacement 5

Note

Although Console users can specify the inventory they want to draw from for individual shipment requests, this option is not available for bulk shipments. Bulk shipment requests for Subscription (1.0) allow only the selection of initial, replacement, or buffer stock. When inventory is not specified or cannot be specified, the system uses the “first in, first out” rule, which means it will deduct from the oldest purchase order first.

Step 6:

The ChannelPartnerId column also calls for an integer.

The entity through which you submit a PO is always referred to as a channel partner, even if it was a direct purchase. Yubico’s Channel partner ID (or ChannelPartnerId or channelpartner_id) is “1”.

Note

The selection of channel partner is not supported in the /shipments API.

Because inventory is sorted according to the source from which it was purchased, when requesting shipment, distinguish between inventory purchased directly from Yubico and inventory purchased from Yubico’s channel partners. The Dashboard shows your total inventory of any given product, combining quantities purchased from all sources: both directly from Yubico and indirectly through channel partners. To find out what is in which inventory, check your purchase orders.

To find out what the channel partner ID is:

BEFORE shipment:
 

The name of the channel partner are shown on the Purchase orders tab, and the channel partner ID is shown on the PO detail popup accessed by clicking on the Purchase order number:

_images/po-detail-1000-50-250.png
AFTER shipment:

The Channel partner ID is shown on the shipment request detail page, accessible by clicking the ID of the shipment request on the Shipments tab.

_images/ship-req-detail.png
Step 7:

When you have finished populating the CSV file:

  1. On the Bulk Shipment tab, click Choose file.

  2. Select your CSV file, and then click Upload.

    If your CSV file uploads successfully, after pre-checks have been performed, notification of success appears under the Upload button.

  3. You are prompted to confirm the file you are uploading (by line count).

If you later find that there were errors in the uploaded file, you can delete some or all of the rows (see Editing or Deleting a Shipment and/or Deleting Shipments).

Note

It can take some time before your requests appear in the list of shipment requests. Always allow time for corrections in case the system finds addresses marked as Incomplete - see below, Reviewing Incompletes.

Shipment Request Fields

In the table below, all fields not marked as mandatory are optional. The Limit column displays the maximum number of alphanumeric characters permitted per field/table cell.

Shipment Request Fields
 
Console: Field Label
CSV: Column Heading
Description Limit
 
Country code
country_code_2
Mandatory. Country code from available_countries.csv 2
1 Company recipient Mandatory if name of recipient is not provided 20
First name
recipient_firstname
Name of recipient. Mandatory if company name not given 15
Last name
recipient_lastname
Recipient’s family name. Mandatory, absent company name 20
 
Address 1
street_line1
Mandatory. First line of address 60
 
Address 2
street_line2
Mandatory if address undeliverable without (e.g. suite #) 60
 
Address 3
street_line3
Not supported for expedited/rush orders 60
  City Mandatory. City, town, or township 60
2
Region/State
region



For the US and Canada, USPS codes are mandatory. See
USPS Codes for US and Canada. (Console users: Select code
from dropdown). For other countries, region or state is
mandatory if the address is not deliverable without it.
To check address deliverability, see footnote to table.
50
 
Postcode
postal_code
Zip code or postal code 50
 
RecipientEmail
recipient_email
Recipient’s email address 80
3
Contact Phone
RecipientTelephone
recipient_telephone


Mandatory. Telephone number of shipment recipient
The limit is 40 of the alphanumeric characters
“0-9+-( )” unless the country code is IN, in which
case the limit is 255. Any format is acceptable,
with or without spaces
40
4
DeliveryType
delivery_type
Type of shipping, “Normal” (1) or “Expedited” (2).
Integers (mandatory for API) OR words
5 InventoryType
Mandatory. Console users select from dropdown. For bulk
orders and API users, see Product ID and Inventory Product ID.
6
ChannelPartnerId
channel_partner_ID
Mandatory. If inventory was purchased directly from
Yubico, enter “1”; if not, enter the ChannelPartnerId
3
  Yubikey 5 NFC Number of keys to be shipped 3
  YubiKey 5 Nano Number of keys to be shipped 3
  YubiKey 5C Number of keys to be shipped 3
  YubiKey 5C Nano Number of keys to be shipped 3
  YubiKey 5Ci Number of keys to be shipped 3
  YubiKey 5Ci FIPS Number of keys to be shipped 3
  YubiKey 5C NFC FIPS Number of keys to be shipped 3
  YubiKey 5C Nano FIPS Number of keys to be shipped 3
  YubiKey 5C FIPS Number of keys to be shipped 3
  YubiKey 5 NFC FIPS Number of keys to be shipped 3
  YubiKey 5 Nano FIPS Number of keys to be shipped 3
 
YubiKey C Bio -
FIDO Edition
Number of keys to be shipped 3
  YubiKey Bio - FIDO Edition Number of keys to be shipped 3
 
Security Key NFC
by Yubico (Black)
Number of keys to be shipped 3
 
Security Key C NFC
by Yubico (Black)
Number of keys to be shipped 3
 
Security Key NFC
by Yubico -
Enterprise Edition
Number of keys to be shipped 3
 
Security Key C NFC
by Yubico -
Enterprise Edition
Number of keys to be shipped 3

Footnote: To find out if an address is deliverable, make a shipment request and see what status code or message it gets. Deliverability is determined by our shipping partners, and it is their codes and messages we display when it comes to questions of deliverability. For a fuller explanation, see Troubleshooting.

Deleting Shipments

This capability applies only to requests that are still editable. To delete shipment requests,

Step 1:

On the Shipments tab, go to the Actions list dropdown, and select Bulk operations. The Bulk Operations screen appears, showing only the shipment requests that can be deleted (i.e., those that have not yet been processed).

Step 2:

Select the checkbox in the row you want to delete (or, to delete all, select the checkbox in the header row), then hit the Delete shipments button on the upper right. The selected shipment requests are deleted.

To revert the Select all action, i.e., to deselect all the shipment requests, click the checkbox in the header row again.


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