API Shipment Requests: Listing, Tracking, Searching and Status

Listing Shipment Requests

There is a 100-record limit on all API calls. To illustrate, using /shipments_exact to retrieve a list of all shipments would be unsuccessful unless there were only one hundred or fewer shipments, as only the first 100 records are returned.

Note

The /shipments_exact{id} route returns the shipment type (‘Automated’ or ‘Manual’) as part of the response. The field is sortable. The /shipments/search-description route returns the Type field as a filterable field.

Obtaining Further Records

In cases where there are more than 100 shipments, iterate through the shipments based on the number of shipments provided by the total_count parameter.

Use the optional parameters to obtain more records. For example:

// get the first 100
/shipments_exact?limit=100&offset=0

// get the second 100
/shipments_exact?limit=100&offset=100

// get the third 100
/shipments_exact?limit=100&offset=200

Single Shipment Request Tracking Example

A successful response from the shipments_exact resource will include a shipment_id which can be used to get the tracking information for this shipment request.

{
   "shipment_id": "U89bvfKKCtQfhnqaFBrAZW",
   "shipment_items": [
      {
            "inventory_product_id": 15,
            "shipment_product_id": "MZ9bmEYFpKKviHe8nSiq4W",
            "shipment_id": "U89bvfKKCtQfhnqaFBrAZW",
            "product_id": 3,
            "product_name": "YubiKey 5C",
            "product_sku": "5060408461488",
            "product_tier": 2,
            "shipment_product_quantity": 16
      }
   ],
   "organization_id": "UEayb8v4LTHdAshpnk1gMd",
   "user_id": "WMktp3sgPSFt4zsgpLDF46",
   "country_code_2": "US",
   "is_delivered": false,
   "is_sent_to_fulfillment": false,
   "is_shipped": false,
   "recipient": "Example Inc.",
   "recipient_email": "jan.lindberg@example.com",
   "recipient_firstname": "Jan",
   "recipient_lastname": "Lindberg",
   "recipient_telephone": "555-5555",
   "street_line1": "7788 Foxrun Street",
   "city": "Dedham",
   "region": "MA",
   "postal_code": "02026",
   "delivery_type": 1,
   "shipment_state_code": "ShipmentStateAwaitingValidation",
   "shipment_state_id": 3,
   "shipment_state_message": "Awaiting Validation",
   "shipment_summary_description": "Total Keys: 16 yk5c:16",
   "shipment_request_date": "2020-12-10T19:56:57Z",
   "shipment_updated_date": "2020-12-10T19:56:57Z",
   "total_keys_shipped": 16
}

Tracking a Shipment Using the shipment_id

curl "https://api.console.yubico.com/v1/shipments_exact/Bj4pfrBJ1SCvkTbTP88Ak2" \
--header "Content-Type: application/json" \
--header "Authorization: Bearer eyJhb..." \

Filtering and Pagination

Refer to the API docs for the GetShipmentsExact operation.

Status

Shipment Status Codes

A shipment request can be edited at any of the states between 1 and 9. From this point on, a shipment request is either processed through to an end state, or set back to state 99.

For information on how address validation affects the success of a shipping request, see the Troubleshooting chapter.

Shipment state codes
shipment_state_code
shipment_state_id
Status description
(shipment_state_description)
Status message in Console
(shipment_state_message)
ShipmentStateIncomplete
1
Shipment request received
by YubiEnterprise Delivery
system but contained some
data that could not be
processed. (2), (3)
Incomplete Shipping
Request
ShipmentStateDraft
2
Shipment request is being
edited and is not ready for
processing.
 Draft
ShipmentStateAwaitingValidation
3
Shipment request received,
no validation done yet.
 Awaiting Validation
ShipmentStateProcessingAddress
4
Shipment request locked as
it undergoes country check,
address validation, sales
tax rate lookup (US), DPL
check.
 Processing
ShipmentStateAddressValid
5
Shipment request address has
been validated, ready to be
picked up by fulfillment
processor.
 Accepted for Fulfillment
ShipmentStateAddressInvalid
6
Shipment request address is
invalid but an alternative
address has been found and
suggested. (2), (3)
 Incomplete
ShipmentStateAddressFail
7
Shipment request address
could not be validated and
no alternative could be
found for suggesting.
suggested. (2), (3)
Address is undeliverable
or could not be
understood
ShipmentStateError
8
Shipment request has failed
processing due to
insufficient credits
or insufficient inventory.
Error: Processing Error,
contact Support
ShipmentStateDPLMatch
9
Shipment request recipient
found on DPL, therefore it
is illegal to fulfill this
shipment request. (4)
 Error: DPL Match
ShipmentStateRequested
12
Used for manual shipments
that are requested but have
not yet been shipped.
 Requested
ShipmentStateShipmentError
99
Shipment request rejected
from ShipmentState-
ProcessingFulfillment
with “%s” error message;
could not be fulfilled by
processor.
Error: Shipping error,
contact Support
ShipmentStateProcessingShipment
100
Shipment request was locked
at 1000hrs UTC to calculate
and deduct tax, inventory,
and credits. (1)
Processing: Inventory &
Tax Deductions
ShipmentStateFulfillmentReady
101
Shipment request ready to be
queued for fulfillment.
Processing: Ready for
Fulfillment
ShipmentStateProcessingFulfillment
102
Shipment sent for fulfill-
ment at 10:00am (or cutoff
time. (1)
Processing: Sent for
Fulfillment
ShipmentStateShipped
103
Shipment sent out by
fulfillment processor and is
in transit.
 Shipped: In transit
ShipmentStateShipped
104
Shipment delivered.

 Delivered
ShipmentStateLost
105
Shipment lost and delivery
is no longer expected.
 Shipment Lost/Missing
ShipmentStateDeliveryException
106
Customs hold or undelivered
or returned shipment to
sender or any other shipping
exceptions.
 Delivery Exception
ShipmentStateDPLConfirmed
107
A shipment that was
automatically detected as a
DPL match has been reviewed
by Yubico and found to be a
confirmed match (not false
positive). The shipment will
not be processed.
DPL Confirmed
ShipmentStateCancelled
108
The shipment has been
cancelled, for example
because a logistics partner
is not able to ship the
order. Cancelling is a manual
action done by Yubico.
Cancelled
ShipmentStateReturnedToSender
110
Shipment has bounced and
been returned to sender
(Yubico or one of Yubico’s
logistics partners).
Returned to Sender
ShipmentStateShippingQueue
1025
Shipment queued for
fulfillment.
Processing:
Queued for Fulfillment
ShipmentStateManualFulfillment
2000
Shipment is being fulfilled
manually. No further action
by shipment requestor is
required.
 Manual Processing

(1) Refer to Timing for cutoff times.

(2) Incomplete Address: Secondary line information such as apartment (apt), suite, unit is missing. Therefore it is not possible to guarantee delivery to the correct recipient.

(3) Address is Undeliverable or could not be understood: The address is either not physically deliverable or it could not be resolved to a real location.

(4) Any shipping request with a recipient name and/or address found on the US government’s DPL (Denied Parties/Persons List) cannot be fulfilled.

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.

YubiEnterprise Delivery API status messages
Message Explanation
InventoryProductId not specified for
ProductId %d - ShipmentStateError
See Bulk Shipment: Shipping to Multiple Addresses
YubiEnterprise Delivery system
Too many keys in shipment -
TotalKeysShipped %d > %d - ShipmentStateError
See Limits and Constraints
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

Response Request Status Codes

The responses to your requests indicate what is happening on the server side. Below are the common status codes in responses from the YubiEnterprise Delivery API, and what they mean.

Status codes
Code Meaning Explanation
200 OK
The request was successful and the response
body contains the representation requested
302 FOUND
A common redirect response; this will
redirect to the OAUTH login page
400 BAD REQUEST API validation failed for the request
403 FORBIDDEN
API denied permission to fulfill the
requested resource
404 NOT FOUND The requested resource was not found

Deprecated APIs

The following table lists deprecated APIs related to listing, tracking, searching, and status for shipment requests. For more information, see Deprecated APIs: Overview.

Shipping Requests: Listing, Tracking, Searching, Status etc.

Deprecated Replacement
GET /shipments GET /shipments_exact
POST /shipments POST /shipments_exact
GET /shipments/{shipmentId} GET /shipments_exact/{shipmentId}
PUT /shipments/{shipmentId} PUT /shipments_exact/{shipmentId}
DELETE /shipments/{shipmentId} DELETE /shipments_exact/{shipmentId}
/UpdateShipmentById shipments_exact/{shipment_id}
/organization/update-setting None

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