.. Shipments.rst .. _shipments-label: ==================== Shipment Requests ==================== This section describes the concepts of shipment requests and processing in YubiEnterprise Delivery services. For instructions on how to work with shipment requests, see :ref:`requesting-shipment-label`. You can manage shipments from your inventory of purchased products on the **All shipments** page. Even if not all your products are being shipped through YubiEnterprise Delivery, you can track shipment requests regardless of how those shipments are processed by Yubico. .. image:: graphics/shipments-overview2.png :width: 800 Shipments processed through YubiEnterprise Delivery (Console or API) are considered "Automatic", whereas the shipments created by Yubico or a channel partner at your request are considered "Manual". The **Type** column on the **All shipments** page in the Console displays the type of shipment. The **Status** column shows the :ref:`shipment-request-id-label`. In the Console, you can create shipment requests from the All shipments page, or from subscription cards on the :ref:`Dashboard `. You can create shipment requests to ship to a :ref:`single address ` or to :ref:`multiple addresses `. Developers can create shipment requests to ship to a single address using the :ref:`YubiEnterprise API `. If your organization is using pre-registered keys, you can request shipments through your :ref:`identity provider `. .. _shipment-processing: Shipment Processing ====================== To maintain the window during which shipment requests can be updated or cancelled, shipments are held and processed in batch. Therefore there might be less inventory available by the time an order is processed than what was shown in purchase order details when the request was created. Processing of shipments happens once a day, and the inventory counts on the :ref:`Console Dashboard ` are only updated after this step. If an inventory for a product is empty (0), you cannot create shipment requests for that product inventory in the Console. However, because processing only happens once a day, this means that inventory can be over-requested before the processing occurs. Say for example you have 100 remaining inventory for YubiKey 5C NFC keys. If you create a shipment request containing 75 YubiKey 5C NFC keys, you will not see a deduction in inventory until the shipment processing step occurs. This is not real-time, and if you place the order in the morning, you will still see a remaining inventory of 100 for the rest of the day. In that time, someone else in your organization could place another shipment for 50 YubiKey 5C NFC keys. When the system eventually processes these shipments, the first one will succeed. The second one will fail due to insufficient inventory with the Console message “Error: Processing Error, contact Support”. To resolve this you can `contact Yubico `_ to request more inventory, and either :ref:`update the product selection ` for the shipment request, or cancel it and create a new one when there is inventory available. If you are using an *API integration* to create shipment requests, a shipment request can be accepted even if there is no inventory for a product. This is to account for the case of products being added later when you purchased more inventory. These shipment requests will fail but can be deleted or resubmitted for processing once more inventory is obtained from Yubico. When using the API it is recommended to :ref:`verify inventory availability ` before creating a shipment request to avoid insufficient inventory errors. .. _timing-label: Time Frames ------------- The following describes important shipment processing and delivery-related time frames: * **Shipment requests:** Shipment requests can be edited or deleted until **2am PST (10am GMT)**, the day **after** they were entered. For more information, see :ref:`editing-shipment-label`. * **Address validation:** Because the system validates addresses every 15 minutes, it can take up to 15 minutes to see if a shipment request has been queued for fulfillment. For more information, see :ref:`shipment-statuses`. * **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. .. note:: Shipments to India might take 6-8 weeks to deliver. * **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. .. _shippable-inventory-label: Shippable Inventory =================== On certain occasions, shippable quantities for a product might be *allocated*, for example due to limited availability. Inventory allocation is also used for shipment of customized keys to indicate the number of pre-programmed keys available for shipment. If there is an inventory allocation set for a specific product you will see the availability in the **Create shipment request** form when requesting shipments. .. image:: graphics/shippable-inventory1.png :width: 500 If there are no shippable products available, you will not be able to request shipments. The allocation is removed or updated as soon as the affected products become available. By default, the Dashboard only displays inventory that can be shipped through *automated shipments* using YubiEnterprise delivery services. To display the actual total remaining available allocated inventory number that can be shipped using manual *and* automated shipments, switch the **Only show shippable inventory** toggle at the top right of the Dashboard to "off". .. _address-validation: Address Validation ================== Incomplete or incorrect address information might cause validation errors. 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 with status "Address Validation Failed" in the All shipments page in the Console. These incomplete shipments must be reviewed and the proposed change accepted or rejected before the request can be processed. For more information, see :ref:`incompletes-label`. Even if an address exists in an address directory it does not mean that the address is deliverable. "Deliverable address" is a United States Postal Service (USPS) classification for addresses to which the USPS has historically been able to deliver. YubiEnterprise Delivery's ability to deliver is based on address information being entered in the format acceptable to the relevant address validation service. The USPS-acceptable formats are described in the USPS's `Postal Addressing Standards `_. YubiEnterprise Delivery uses a third-party address validation service that performs a deliverability assessment for US domestic shipments. This assessment can deem an inaccurate address as "deliverable," leading to successful delivery despite the inaccuracy. For compliance reasons, the inaccurate address will not be updated in the Console or API. The deliverability assessment only applies to addresses in the US. For parts of the world with less standardized address formats, the fact that YubiEnterprise Delivery can accept an address does not mean that it is deliverable. An address is often classified as "partially deliverable". This means that delivery relies on local couriers familiar with their urban systems and routes to deliver to intended recipients, especially in destinations where there are no numbers in the postal addresses. .. note:: The YubEnterprise address validation service validates that the "Region" field has the required standardized two-letter USPS region code for shipments going to the US and Canada. If the region code is missing in these cases, the shipment request will fail the address validation. For more information, see :ref:`usps-codes-label`. .. _limits+constraints-label: .. _limits+constraints: .. _restrictions-label: Recipient Information ---------------------- When creating shipment requests, either a recipient first name and last name, or a company name are required. If needed you can provide both when creating a shipment request to a *commercial* address. However, because the system address validation recognizes commercial addresses, you should not provide a company name if shipping to a *residential* address as this might cause delivery issues. Only latin characters are permitted. The reason for this is to avoid issues where carriers are not able to print address labels with non-latin characters. Accented characters (à, á, ä etc.) are permitted. Long street names in recipient addresses can be problematic because the shipment request might fail if the contents of the recipient address fields in the shipment request exceed the maximum number of characters permitted. In cases where the shipment address is longer than what is accepted by the associated carriers, the shipment will fail validation with the status “Address Not Accepted by Carrier”. When creating a shipment request using the shipment request form in the Console, the Address line 1 (required) and Address line 2 (optional) fields are available for entering the recipient address. The following limitations apply: * The maximum number of characters allowed in each of the two address fields is 60. * When shipping to *India*, the total maximum allowed characters combined between Address line 1 and Address line 2 is *120*. * For *every other destination country*, the maximum number of allowed characters combined between the two address fields is *105*. * In case of a long address, the system will try to split the address to fit within the character limits. Even if an address contains less than 120 characters, the shipment request might fail if the system cannot find a place in the address to split the lines between the fields. If a shipment request fails with the status “Address Not Accepted by Carrier” an email is sent notifying the requester about the failure. The requester is asked to :ref:`edit the shipment request ` to shorten or split the address, and resubmit the shipment request. For more information about character limits, see :ref:`csv-col-headings-label`. Address validation override cannot be applied for validation failures of type “Address Not Accepted by Carrier”. .. _po-box-label: 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. Address Validation Override ----------------------------- The Yubico address validation service sometimes gives an error even if an address is valid. You have the option to override the Yubico validation warnings if you are confident that an address is valid. This feature is also useful if for example you are using a different address validation service than the Yubico one. .. important:: Be aware that if you override the Yubico address 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. When the address validation is overridden for a shipment, its status changes from “Address validation failed” to “Accepted for Fulfillment”. Shipments for which address validation have been applied are indicated in the **Address validation override** column in the **All shipments** page. Address validation can be skipped for failed shipments, or when creating shipments. For more information, see :ref:`overriding-address-validation`. .. _email-label: Shipment Notifications =========================== The YubiEnterprise Delivery system automatically sends notification messages related to the various :ref:`shipment statuses `, for example shipments that failed and require user interaction. Notification messages are displayed in the :ref:`Console notification center `, as well as sent by email to relevant recipients. The following applies to notification messages: * Notification emails are sent for shipments created both from the Console and the API, for example integrations such as :ref:`FIDO Pre-reg ` (shipments of pre-registered YubiKeys). * For shipments with statuses "Address Validation Failed" and "Address Not Accepted by Carrier", the email is sent to the shipment *requestor*, both for :ref:`single-address ` shipment requests and shipment requests created through a :ref:`CSV upload ` (multi-address shipment request). * Tracking details, delivery, and delivery exception emails are only sent to the *recipient* of the shipment. If no recipient email is provided in the shipment request, then no email is sent. * To consolidate the information in case of multiple failures, email notifications are aggregated into hourly or daily emails depending on the criticality of the notification. * For emails that go to the shipment *requestor*, if they mark them as read in the Notification Center in the Console before the scheduled time that the email digest is sent, the notification message will not be included in the digest email. * If a replacement shipment was created by Yubico, by default the email notifications are sent to the original shipment requestor. However, this can be changed by Yubico when creating the replacement shipment. Once the replacement shipment is created, the email address cannot be changed. .. _country-codes: Country Codes =============== When creating shipment requests to multiple addresses (bulk shipments) or through the API, this requires entering a two-letter country code as part of the shipment address. The country codes used in the system follows the international two-letter country code standard. To ensure you are using the correct country code, you can download a CSV file containing country codes for all the countries available for shipments for that specific organization. For more information, see :ref:`creating-recipient-information-file-label`. .. _usps-codes-label: USPS Region/State Codes ========================= Shipments going to the US and Canada require a standardized two-letter USPS region code listed below. .. table:: **USPS Codes for US and Canada** +-----------------------------------------------+----+ |State (US) / Province or Territory (Canada) |Code| +===============================================+====+ |Alabama |AL | +-----------------------------------------------+----+ |Alaska |AK | +-----------------------------------------------+----+ |Alberta |AB | +-----------------------------------------------+----+ |American Samoa |AS | +-----------------------------------------------+----+ |Arizona |AZ | +-----------------------------------------------+----+ |Arkansas |AR | +-----------------------------------------------+----+ |British Columbia/Colombie-Britannique |BC | +-----------------------------------------------+----+ |California |CA | +-----------------------------------------------+----+ |Colorado |CO | +-----------------------------------------------+----+ |Connecticut |CT | +-----------------------------------------------+----+ |Delaware |DE | +-----------------------------------------------+----+ |District of Columbia |DC | +-----------------------------------------------+----+ |Florida |FL | +-----------------------------------------------+----+ |Georgia |GA | +-----------------------------------------------+----+ |Guam |GU | +-----------------------------------------------+----+ |Hawaii |HI | +-----------------------------------------------+----+ |Idaho |ID | +-----------------------------------------------+----+ |Illinois |IL | +-----------------------------------------------+----+ |Indiana |IN | +-----------------------------------------------+----+ |Iowa |IA | +-----------------------------------------------+----+ |Kansas |KS | +-----------------------------------------------+----+ |Kentucky |KY | +-----------------------------------------------+----+ |Louisiana |LA | +-----------------------------------------------+----+ |Maine |ME | +-----------------------------------------------+----+ |Manitoba |MB | +-----------------------------------------------+----+ |Marshall Islands |MH | +-----------------------------------------------+----+ |Maryland |MD | +-----------------------------------------------+----+ |Massachusetts |MA | +-----------------------------------------------+----+ |Michigan |MI | +-----------------------------------------------+----+ |Micronesia |FM | +-----------------------------------------------+----+ |Minnesota |MN | +-----------------------------------------------+----+ |Mississippi |MS | +-----------------------------------------------+----+ |Missouri |MO | +-----------------------------------------------+----+ |Montana |MT | +-----------------------------------------------+----+ |Nebraska |NE | +-----------------------------------------------+----+ |Nevada |NV | +-----------------------------------------------+----+ |New Brunswick/Nouveau-Brunswick |NB | +-----------------------------------------------+----+ |New Hampshire |NH | +-----------------------------------------------+----+ |New Jersey |NJ | +-----------------------------------------------+----+ |New Mexico |NM | +-----------------------------------------------+----+ |New York |NY | +-----------------------------------------------+----+ |Newfoundland/Terre-Neuve |NF | +-----------------------------------------------+----+ |North Carolina |NC | +-----------------------------------------------+----+ |North Dakota |ND | +-----------------------------------------------+----+ |Northern Mariana Islands |MP | +-----------------------------------------------+----+ |Northwest Territories/Territoires du Nord-Ouest|NT | +-----------------------------------------------+----+ |Nova Scotia/Nouvelle-Écosse |NS | +-----------------------------------------------+----+ |Nunavut |NU | +-----------------------------------------------+----+ |Ohio |OH | +-----------------------------------------------+----+ |Oklahoma |OK | +-----------------------------------------------+----+ |Ontario |ON | +-----------------------------------------------+----+ |Oregon |OR | +-----------------------------------------------+----+ |Palau |PW | +-----------------------------------------------+----+ |Pennsylvania |PA | +-----------------------------------------------+----+ |Prince Edward Island/Île-du-Prince-Édouard |PE | +-----------------------------------------------+----+ |Puerto Rico |PR | +-----------------------------------------------+----+ |Quebec/Québec |QC | +-----------------------------------------------+----+ |Rhode Island |RI | +-----------------------------------------------+----+ |Saskatchewan |SK | +-----------------------------------------------+----+ |South Carolina |SC | +-----------------------------------------------+----+ |South Dakota |SD | +-----------------------------------------------+----+ |Tennessee |TN | +-----------------------------------------------+----+ |Texas |TX | +-----------------------------------------------+----+ |U.S. Virgin Islands |VI | +-----------------------------------------------+----+ |Utah |UT | +-----------------------------------------------+----+ |Vermont |VT | +-----------------------------------------------+----+ |Virginia |VA | +-----------------------------------------------+----+ |Washington |WA | +-----------------------------------------------+----+ |West Virginia |WV | +-----------------------------------------------+----+ |Wisconsin |WI | +-----------------------------------------------+----+ |Wyoming |WY | +-----------------------------------------------+----+ |Yukon |YK | +-----------------------------------------------+----+ Status and Error Messages ========================== During processing a shipment request goes through different statuses. You can view the status for a shipment in the **Status** column of the **All shipments** page. For information about various shipment statuses and how to solve shipment request validation issues, see :ref:`solve-shipment-issue`. For explanations of shipment error messages in the API, see :ref:`shipment-error-msg-label`. .. _inventory-options-label: Subscription Inventories ============================== The following provides an overview of subscription inventory options that might be available for your organization, and that you will choose from when creating shipment requests. For more information about subscription plans and options, see :ref:`modes-of-purchase`. .. note:: If you have inventory from a Subscription 1.0 purchase (legacy), you might also see inventory of type Initial and Buffer. .. include:: includes/2.0-subscr-tier-structure.rst ------------------------------------- To file a support ticket for YubiEnterprise Delivery, click `Support `_.