Skip to main content

Creating a shipment

To inform topi and thereby the customer of a shipment, call the create shipment endpoint.

Most items will require a serial number, which can be provided to the endpoint by mapping them to an object that contains the seller_product_reference of the item and the serial_number. A list of these objects is then added to the payload as serial_numbers. The presence of an object in the array -- with the item reference -- indicates that it is being shipped. Items with a quantity greater than one need to be repeated in the array, with the same reference, but their individual serial numbers.

Example: A shipment of two Macbooks of the same kind (same product reference).

{
    "order_id": "d7f99b4d-806b-4d17-b44a-de8d01cd45e3",
    "serial_numbers": [
        {
            "seller_product_reference": {"source": "MYERP", "reference": "000123456"},
            "serial_number": "S01111111"
        },
        {
            "seller_product_reference": {"source": "MYERP", "reference": "000123456"},
            "serial_number": "S02222222"
        }
    ],
    "tracking_url": "https://shipment-provider.com/tracking/123456789"
}

Partial shipments​

We allow partial shipments, which means you can call the endpoint for a subset of items. You must not repeat the already shipped items in subsequent shipment calls, with the exception of updating Tracking URLs.

We expect all items to be sent eventually, so that we can acknowledge ther order as fully shipped.

No Serial Number for item​

Items that do not have a serial number need to be explicitly provided with their reference and "" as the serial number, so that we can acknowledge that the item has been shipped.

If you provide an empty serial number for an item that requires a serial number, the request will fail with a 400 Bad Request.

Cross-referencing​

We support multiple product references for each product in the catalog you provide to us. This is be useful if you need to use more than one system.

If one product reference is used for the creation of the offer (e.g. {"source": "MYERP", "reference": "000123456"}), and the other one (e.g. {"source": "SYS", "reference": "99999999"}) is used for providing the serial numbers, we can establish the match via cross-referencing in the catalog. Any of these references will work for sending the serial numbers.

Tracking URL updates​

If you want to update the tracking URL for an already shipped asset you can reprovide the item by its reference with the already assigned serial number and a new tracking_url.

This request will fail with a 400 Bad Request if a different serial number is provided for the already shipped item. If there are still unshipped item(s) with the same reference and you provide a different serial number, this will not update the shipped item, but instead will mark the unshipped item(s) as shipped.

Bad Request Errors​

A 400 Bad Request response can happen due to different reasons:

  • The number of provided serial numbers for a given reference is greater than the number of items in the order.
  • Attempt to overwrite an already assigned serial number. We can only process overwriting of serial numbers as manual support requests.
  • Assigned an empty serial number "" to an item that requires a serial number.