Requesting Shipment: Introduction

Shipments: Overview provides general information about shipment, whereas this section provides more specific information.

The different methods of requesting shipment each have their own subsection; the information in this current section applies to all methods.

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.

The Dashboard displays cards for each of the different subscription plans/tiers within the primary, backup and replacement categories. Each card shows the licenses available and the total licenses in the form of numbers and a circular graphic showing the amount of product consumed and remaining. In addition, the supported form factors for each plan/tier/category can be viewed. The screenshot below shows an example of Subscription (2.0).

_images/dashboard-sub-mgmt-2.0.png

To view the form factors available for each type of subscription, click the left-pointing caret on the right of the title bar on the card for each type of subscription. The Form factors available popup opens on the card. This is shown on the top two cards in the screenshot above; the bottom two cards have unclicked carets and thus do not display the available form factors.

You can put in a shipment request directly from each subscription card as well as from within the Form factors available window. For more information on creating shipment requests, see Requesting Shipment: Introduction.

Subscription (2.0) is differentiated from Subscription (1.0), and the standard products inventory is shown simply as form factors available.

_images/dashboard-sub-mgmt-1.0.png

In the examples shown above, we see the subscription tiers purchased plus inventory available in addition to standard product inventory. Recent Shipments is shown on the Dashboard below that, along with Recent Purchase Orders (POs). Entitlement to products for each subscription tier is given in Key Models Per Tier.

Address Validation

When Yubico’s address validation service catches a discrepancy between an address in a shipment request and post office standards, the system flags the affected shipment request. Requests with such discrepancies are shown as “Incomplete” in the Status column of the Console. Incompletes must be reviewed and the proposed change accepted or rejected before the request can be processed. For instructions, see Reviewing Incompletes.

Restrictions

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.

Inventory: Channel Partners

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

Limits and Constraints

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

Address validation takes place every 15 minutes. This means that you might have to wait up to 15 minutes to find out if your shipment request has been queued for fulfillment (see Shipping Status Codes).

Non-subscription purchases: Shipment requests can be made for up to one year after a PO is submitted.

Subscription purchases: Availability of products in shipment requests depends on the stock/inventory from which the products are drawn. (For details, see Tier Sub-categories.)

Inventory Matters

Subscription (2.0)

Subscription (2.0) Full List of Inventory (Stock) Types
Name of Tier
Initial or
Replacement
Primary or
Backup
Console: “From Stock” dropdown
Inventory Option
Base Tier Standard
(FIDO-only key license(s))
Security Keys only
Initial Primary Base Standard Primary
Backup Base Standard Backup
Replacement Primary Base Standard Primary Replacement
Backup Base Standard Backup Replacement
Base Tier Plus
Initial Primary Base Plus Primary
Backup Base Plus Backup
Replacement Primary Base Plus Primary Replacement
Backup Base Plus Backup Replacement
Advanced Tier Standard
(Multiprotocol key license(s))
YubiKey 5 Series including
YubiKey 5 Ci
Initial Primary Advanced Standard Primary
Backup
Advanced Standard
Backup
Replacement Primary Advanced Standard Primary Replacement
Backup Advanced Standard Backup Replacement
Advanced Tier Plus
Initial Primary Advanced Plus Primary
Backup Advanced Plus Backup
Replacement Primary Advanced Plus Primary Replacement
Backup Advanced Plus Backup Replacement
Compliance Tier Standard
(Certified key license(s))
FIPS, CSPN
Initial Primary Compliance Standard Primary
Backup Compliance Standard Backup
Replacement Primary Compliance Standard Primary Replacement
Backup Compliance Standard Backup Replacement
Compliance Tier Plus
Initial Primary Compliance Plus Primary
Backup Compliance Plus Backup
Replacement Primary Compliance Plus Primary Replacement
Backup Compliance Plus Backup Replacement

Subscription (1.0)

The full list of options that were potentially available in Subscription (1.0) is given below. The actual list depends on what you have purchased. Explanations for the terms in the list are given in the table below the list. For more details on subscription and non-subscription purchasing, see Modes of Purchase.

Subscription (1.0): Full List of Inventory Types

  • Primary Subscr - Base Tier: Initial
  • Primary Subscr - Base Tier: Buffer
  • Primary Subscr - Base Tier: Replacement
  • Primary Subscr - Adv. Tier: Initial
  • Primary Subscr - Adv. Tier: Buffer
  • Primary Subscr - Adv. Tier: Replacement
  • Primary Subscr - Prem. Tier: Initial
  • Primary Subscr - Prem. Tier: Buffer
  • Primary Subscr - Prem. Tier: Replacement
  • Primary Subscr - FIPS Tier: Initial
  • Primary Subscr - FIPS Tier: Buffer
  • Primary Subscr - FIPS Tier: Replacement
  • Backup Subscr - Base Tier: Initial
  • Backup Subscr - Base Tier: Buffer
  • Backup Subscr - Base Tier: Replacement
  • Backup Subscr - Adv. Tier: Initial
  • Backup Subscr - Adv. Tier: Buffer
  • Backup Subscr - Adv. Tier: Replacement
  • Backup Subscr - Prem. Tier: Initial
  • Backup Subscr - Prem. Tier: Buffer
  • Backup Subscr - Prem. Tier: Replacement
  • Backup Subscr - FIPS Tier: Initial
  • Backup Subscr - FIPS Tier: Buffer
  • Backup Subscr - FIPS Tier: Replacement
  • Non-subscription - Base Tier
  • Non-subscription - Advanced Tier
  • Non-subscription - Premium Tier
  • Non-subscription - FIPS Tier
  • Standard Products
Standard Products Subscription Non-subscription
Standard products are
physical keys purchased
outright (on your PO
you will not find
“Standard Products”,
but instead the actual
products/models that
you purchased).



There is a primary
subscription and a backup
subscription for each
tier (product grouping):
Base, Advanced, Premium,
and FIPS. Each of those
tiers has Initial,
Buffer, and Replacement
sub-categories, explained
in the table below,
The non-subscription
tiers are for virtual
keys. Unlike
subscription tiers,
non-subscription
tiers have no
sub-categories.




Tier Sub-categories

Stock: Initial, Buffer, Replacement
Initial
The stock in this category reflects the
total number of users on the subscription. This
lot can be drawn upon for 12 months from the
start of your subscription term.
Buffer
This category is made available to you free of
charge when your subscription begins. You can
draw on it throughout the term of your
subscription.
Replacement
This category is intended for those who have
lost their YubiKeys or want to upgrade. The
stock in this category is reset each year of
the subscription to the Replacement limit.

Timing

Shipment requests can be edited or deleted until 2am PST (10am GMT), the day after they were entered.

Normal (standard) shipping: Shipments typically will take 5-7 days for transit in North America and Europe. Other parts of the world will incur longer transit times.

Expedited (rush) shipping: Shipments typically will take 1 business day for transit in North America. Other parts of the world may incur longer transit times, but will leverage the fastest time frame reasonably available.

Shipment Status Messages

These error messages accessible via the API tell you why a given shipment request was unsuccessful. It is worth reviewing them before making any shipping requests in order to see what sort of issues might arise and thereby avoid them in the first place.

As the following table is wide, you may need to scroll horizontally. In the Explanation column, the source of the message is given: YubiEnterprise Delivery system for internal messages, US Validation for the US Postal Service, and finally, International Validation. Messages originating from the last two are simply passed on to you by YubiEnterprise Delivery.

YubiEnterprise Delivery API /shipment_exact Status Messages
Message Explanation
InventoryProductId not specified for ProductId %d - ShipmentStateError
YubiEnterprise Delivery system
Too many keys in shipment - TotalKeysShipped %d > %d - ShipmentStateError
YubiEnterprise Delivery system
Not enough Inventory for Shipment - ShipmentStateError
YubiEnterprise Delivery system
Re-enter the address differently; some parts of it are invalid. See
the YubiEnterprise documentation for more guidance.
US Validation
The address is invalid. See the YubiEnterprise documentation for more
guidance.
US Validation
The address is valid.
No further explanation required
US Validation
Remove the ‘secondary unit designator’ (apt, suite, department, etc.)
because it is superfluous.
Remove the apartment number, unit, etc.:
it is considered wrong or unnecessary
US Validation
Enter second line information (apartment, unit, etc.).
The information in the primary line is not specific enough.
Add the apartment number, unit, etc.
US Validation
The address is a valid military address.
No further explanation required
US Validation
The address is a valid General Delivery address where individuals without
permanent addresses can receive mail.
No further explanation required
US Validation
The address is valid. An organization such as a government agency can
can have its own zipcode because it receives a large volume of mail.
No further explanation required
US Validation
Enter a street number; for example, for Yubico ‘Lytton Ave’ alone is not
sufficient, it needs to be ‘530 Lytton Ave’.
The number on the primary line, e.g., the
“185” in “185 Berry Street” is missing
Enter a valid street number.
The number on the primary line, e.g., the
“185” in “185 Berry Street” is not valid
US Validation
Enter a PO Box, Rural Route, or Highway Contract box number.
US Validation
Enter a valid PO Box, Rural Route, or Highway Contract box number.
US Validation
Enter the Private Mailbox (PMB) identifier or the # sign, followed by the
PMB number.
PMB number is Private Mailbox Number
US Validation
This address is not eligible to receive mail.
US Validation
The address is that of a Commercial Mail Receiving Agency (CMRA) a private
business that accepts mail for recipients, and the required private
mailbox information is present.
US Validation
The address is missing some important secondary line information
(apartment, unit, etc).
No further explanation required
International Validation
Mail is unlikely to arrive at this destination - please verify input.
No further explanation required
International Validation
This street could not be found within the city or postal code.
No further explanation required
International Validation
Invalid OrganizationId for Shipment YubiEnterprise Delivery system
Country Code not set for Shipment YubiEnterprise Delivery system
Country could not be found from CountryCode2: %s
Country code entered is not in
YubiEnterprise Delivery system list
Shipment has no shipment items YubiEnterprise Delivery system
DeliveryType not set for Shipment, defaulting to 1 - normal YubiEnterprise Delivery system
Invalid DeliveryType %s for Shipment YubiEnterprise Delivery system
InventoryType not set for Shipment, defaulting to 1 YubiEnterprise Delivery system
InventoryType %s not valid set for Shipment
You cannot use this InventoryType for this
shipment - YubiEnterprise Delivery system
Negative quantity entered for ShipmentItem with ProductId=%d defaulting to 0
You set the quantity of the specified
ProductID to be shipped to less than zero.
YubiEnterprise Delivery system
Invalid ShipmentProductQuantity for ShipmentItem %d
You probably do not have sufficient
inventory - YubiEnterprise Delivery system
Invalid ShipmentProductLineCost for ShipmentItem %d YubiEnterprise Delivery system
Invalid Shipment - Total keys in shipment greater than 500
You cannot ship more than 500 items at
once - YubiEnterprise Delivery system
Shipment has zero total item quantity
The number of items to be shipped must be
> than 0 - YubiEnterprise Delivery system
US Address is missing the state name/abbreviation in region field
No further explanation required
YubiEnterprise Delivery system
Bad ProductId in ShipmentProduct for NewShipmentProduct
ProductID is wrongly specified or invalid
YubiEnterprise Delivery system
Input for %s exceeded limit of %d characters
Specified field cannot accept the number
of characters that were entered.
YubiEnterprise Delivery system
Shipment of these products to this country using this delivery type is
not supported. For more information, see Delivery Policies.
Shipment request contravenes one or more
business rules. YubiEnterprise Delivery
system.

Reviewing Incompletes

The address validation service flags addresses that are problematic or defective in some way, and displays this information on the Console in the Status column on the Dashboard tab. For a complete list of the different statuses and what they indicate, see Shipping Status Codes. To ensure your shipping request is accepted and processed, always verify that it has not been flagged Incomplete.

Step 1:

On the Shipments tab, in the Actions menu next to the Create shipping request button, select Review incompletes. The list of shipping requests with incomplete addresses is displayed:

_images/201857-review-incompletes-ok-copy.jpg

Review incomplete addresses

Step 2:

To find out what is wrong with an address and/or correct it, click the Edit icon at the end of the row containing the item. See Editing or Deleting a Shipment. The Edit shipment screen indicates the problem, as shown in the screenshot below, for example.

_images/201857-undeliverable-name-ok.jpg

Error in name of recipient

Step 3:

The address validation process stops at the first error it finds in a given request (or in the case of a CSV file, in a given row). In the screenshot above, it stopped at the name of the recipient, but the address in the example above would not be validated either. For this reason, continue to run the Review Incompletes activity until no more errors are found in your shipment request.

Editing or Deleting a Shipment

You can update an address or delete a shipping request until it is locked for processing and fulfillment - see Timing. This applies for both Automated and Manual type requests. Note, however, that to edit or delete a Manual request, you must contact Yubico directly. Yubico staff will then go into your console and override the data they input originally and update in accordance with your wishes.

To delete shipment requests made via CSV file, see Deleting Shipments.

Step 1:

To edit a shipment, click the Edit icon in the appropriate row of the table. The Edit shipment - <ID> screen appears, as shown below.

_images/edit-shipment-ok.png

Edit shipment screen

Step 2:

Either make the required changes and click Update or click Delete shipment. The update function validates the fields, with a mouseover warning on any fields requiring input, as shown in the screenshot below:

_images/please-fill-out-this-field.png

Mouseover warning

Step 3:

Verify that the system is able to validate all the input in your shipment request by running the Review Incompletes activity (see Reviewing Incompletes).

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

Viewing Refunds

Org Owners, Admins, and Auditors can access refund details from the Shipments tab. On the upper right, click the Action dropdown menu and select Processed Refunds.”

_images/processed-refunds-menu.png

The list of processed refunds appears. To see further details, click the Shipment ID of the desired item.

_images/lostormissing-detail.png

Downloading List of Refunds

To download a CSV file listing all the data shown on the list of processed refunds, click the Download refund CSV button.

_images/actual-refunds.png