Requesting Shipment: Introduction
This section provides specific information about shipment requests. For a general introduction to shipment requests, see Shipments: Overview.
The different methods of requesting shipment each have their own subsection; the information in this current section applies to all methods.
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.
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 card in the screenshot above; the caret of the card at the bottom is unclicked and thus does 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.
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.
Shippable Inventory
On rare occasions, due to limited availability, shippable quantities for a product are allocated. If there is an allocation set for a specific product you will see the availability on your Dashboard and in the Create shipment request form when requesting shipments.
If there are no shippable products available, you will not be able to request shipments. The allocation is removed as soon as the affected products become available again.
You can enable the Only show shippable inventory toggle switch on the top right of the Dashboard to see products that can be shipped through automated shipments.
If the toggle is turned on, the inventory allocation is displayed only if it has been set for a product that can be shipped using the YubiEnterprise Console (automated shipments). In that case, the remaining product volume supported by automatic shipment is smaller than the actual total remaining available allocated inventory number that can be shipped using manual and automated shipments.
Methods of Requesting Shipment
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. “Channel partner” is a term that covers distributors, resellers, and even Yubico itself. Yubico’s Channel partner ID (or ChannelPartnerId
or channelpartner_id
) is “1”.
Note
The deprecated /shipments
API did not support indirect sales, i.e. the selection of channel partners (distributors, resellers). That API only supported direct sales in that the ChannelPartnerID was always set to 1
, which means Yubico. To order inventory purchased through a distributor or reseller, use the /shipments_exact
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 through distributors and resellers doing business with Yubico. 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 (reseller or distributor) ID is:
BEFORE shipment: | |
---|---|
The name of the channel partner (reseller or distributor) is 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: |
|
AFTER shipment: | The Channel partner ID (Reseller or Distributor) is shown on the shipment request detail page, accessible by clicking the ID of the shipment request on the Shipments tab. |
Limits and Constraints
Names and Addresses: First Line
First name and Last name in the Console and in the CSV file for bulk shipments, 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 and 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, as in this example:
Location | Field (limit=15) | Field (limit=20) | Field (limit=20) |
---|---|---|---|
API | recipient_firstname |
recipient_lastname |
recipient |
CSV | First name | Last name | Company |
Console | First name | Last name | Company |
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 |
Company Name: Second Line
The second line on the shipping label maps to the name of the recipient’s company if the address is not residential. For example, the system’s address verification function recognizes that Yubico’s Santa Clara facility is in a commercial building, therefore the company name is expected in:
The Company field/table cell in the Console and in the CSV file.
The
recipient
field in the APINote
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 therecipient_firstname
andrecipient_last name
fields instead.
If the address is residential, leave empty:
- The Company field/table cell in the Console and in the CSV file.
- The
recipient
field in the API.
Address Information
Incomplete or incorrect address information might cause validation errors. 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
When adding address information, you can for example use the address formats provided by Google Maps, see note in Troubleshooting. The limits on the various fields and the options for the dropdown are given in Shipment Request Form Fields.
- Address Validation
- Every 15 minutes, the system validates addresses; therefore you might have to wait up to 15 minutes to find out if your shipment request has been queued for fulfillment. (For details, see Shipping Status Codes.)
- Availability of Stock/Inventory
- Shipment allocations may be set. (For details, see Shippable Inventory.)
- Non-subscription Purchases
- Shipment requests can be made for up to one year after a PO is submitted.
- Subscription Purchases
- Availability of products depends on the stock/inventory from which the products are drawn. (For details, see Tier Sub-categories.)
Inventory Matters
Subscription (2.0)
Name of Tier
|
Initial or
Replacement
|
Primary or
Backup
|
Console: “Product selection”,
“Products” dropdown
|
---|---|---|---|
Base Standard tier
(FIDO-only key license(s))
Security Keys only
|
Initial | Primary | Base Standard Primary |
Backup | Base Standard Backup | ||
Replacement | Primary | Base Standard
Primary Replacemen
|
|
Backup | Base Standard
Backup Replacement
|
||
Base Plus tier
|
Initial | Primary | Base Plus Primary |
Backup | Base Plus Backup | ||
Replacement | Primary | Base Plus
Primary Replacement
|
|
Backup | Base Plus
Primary Replacement
|
||
Advanced Standard tier
(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 Plus tier
|
Initial | Primary | Advanced Plus Primary |
Backup | Advanced Plus Backup | ||
Replacement | Primary | Advanced Plus
Primary Replacement
|
|
Backup | Advanced Plus
Backup Replacement
|
||
Compliance Standard tier
(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 Plus tier
|
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
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
- Shipment requests can be edited or deleted until 2am PST (10am GMT), the day after they were entered. For instructions on these procedures, see Editing or Deleting a Shipment.)
- Delivery
Normal (standard) shipping: Typically, shipments will take 5-7 days for delivery in North America and Europe. Delivery to other parts of the world will take longer.
Expedited (rush) shipping: Typically, shipments within North America can be delivered in 1 business day. It may take longer to deliver shipments to other parts of the world, but Yubico will leverage the fastest delivery service 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.
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.
Message | Explanation |
---|---|
InventoryProductId not specified forProductId %d - ShipmentStateError
|
YubiEnterprise Delivery system
|
Too many keys in shipment -
TotalKeysShipped %d > %d - ShipmentStateError
|
YubiEnterprise Delivery system
|
Not enough Inventory for Shipment -
ShipmentStateError
|
See Purchase Orders
YubiEnterprise Delivery system
|
Re-enter the address differently; some parts
of it are invalid.
|
See Troubleshooting
US Validation
|
The address is invalid.
|
See Troubleshooting
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 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, for example
the “185” in “185 Berry Street” is missing.
US Validation
|
Enter a valid street number.
|
The number on the primary line, for example
the “185” in “185 Berry Street” not valid.
US Validation
|
Enter a PO Box, Rural Route, or Highway
Contract 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 > 0.
YubiEnterprise Delivery system
|
US Address is missing the state
name/abbrevation 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
|
- See the USPS FAQ.
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: |
---|---|
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 dialog indicates the problem. In the example below, the recipient name is incorrect. |
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 example 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 shipment request until it is locked for processing and fulfillment, see Timing. 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.
Step 1: | To edit a shipment, click the Edit [pencil] icon in the appropriate row of the table. The Shipment details page appears. To make name and/or address changes, scroll down to the Edit Shipment section. |
---|---|
Step 2: | To make changes in either products or inventory, scroll down further to the Product Selection section. Be aware that Shippable Inventory limits might apply. |
Step 3: | 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. |
Step 4: | Verify that the system is able to validate all the input in your shipment request by running the Review Incompletes activity (see Reviewing Incompletes). |
Bulk Deletion of Shipment Requests
To delete multiple shipment requests at the same time, do the following:
Step 1: | On the Shipments tab, go to the Actions dropdown list, and select Bulk operations. The Bulk Operations screen appears showing shipment requests that can be deleted (those that have not yet been processed). |
---|---|
Step 2: | Select the checkbox in the row you want to delete. To delete all, select the checkbox in the header row and click Delete shipments on the upper right. The selected shipment requests are deleted. To revert the Select all action, deselect all the shipment requests by clicking the checkbox in the header row again. |
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
Console 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.
The list of processed refunds appears. 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, or click the Download refund CSV file (see Downloading List of Refunds).
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.
The downloaded spreadsheet 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