API

API endpoints > shipments > post

Add a shipment to the system. This endpoint will use all the methods known to the API. It will run the set up rulebook, try to 'normalize' the address (if possible) and will even try to correct the street and city name according to the given postalcode (if enabled and only possible for certain countries).

Notes

  • If there is any error, the shipment will not be stored at all.
  • Not all fields are mandatory that could be mandatory for the targetted carrier. The api requires a minimal amount of information to enter a shipment.
  • A carrier is not mandatory as long as they are set by a rule or a system default setting.
  • If no service or extra option is given, and is not set by a rulebook rule, then the carrier standard shipment without any options is selected (by the carrier).

JSON data structure

  • ShipmentArray of objectsrequiredMinimum array items: 1, maximum array items: 200Array of shipments to store
    • ClientReferenceCodeStringrequiredMinimum length: 1, maximum length: 100The shipment reference or id (usually the visible order id in the shop platform).
    • ColliCountStringMaximum length: 10The number of colli's in this shipment
    • KeepOrigSourceBooleanWhen using PATCH, do not change the original source of the shipment.
    • Note1StringOptional shipment note, might be used for extra information.
    • Note2StringOptional shipment note, might be used for extra information.
    • OnholdBooleanSet this shipment on hold, so it does not autoselect in dayclosing
    • OrderTotalpriceThe correct monetary value of the entire shipment content
    • ShopItemIdhex stringrequiredMaximum length: 60The id of this shipment/order in the shop platform, for sending back status information.
    • WeightInteger numberThe total weight of the shipment (if not defined, the customs weight or dimensions weight is used, dimensions weight overwrites everything).
    • AddresssublistrequiredAddress information
      • CityStringrequiredMinimum length: 2, maximum length: 50Cityname
      • CompanyNameStringMinimum length: 1, maximum length: 100Optional company name
      • CountryCountryrequiredMinimum length: 2, maximum length: 3Country, iso3 format
      • EmailE-mailMinimum length: 2, maximum length: 100Email address (required for some carriers)
      • HouseNumberInteger numberMinimum value: 1Housenumber
      • NameStringrequiredMinimum length: 1, maximum length: 100Person name
      • NeighborhoodStringMaximum length: 50Neighborhood/community
      • NumberExtensionStringHousenumber extension (floor, a, etc.)
      • PhoneStringMinimum length: 5, maximum length: 20Phone number (required for some carriers)
      • PostalCodeStringrequiredMinimum length: 3, maximum length: 15Postalcode
      • StateStringMinimum length: 2, maximum length: 50State/province name (required in some countries)
      • Streetname1StringrequiredMinimum length: 3, maximum length: 100Street name line 1 (can include housenumber if not defined in HouseNumber)
      • Streetname2StringMaximum length: 100Street name line 2, not supported by all carriers!
    • CarriersublistThe carrier to use for this shipment
      • IdInteger numberrequiredMaximum value: 999The correct carrier id (found in the /carriers/ endpoint)
    • CustomssublistCustoms information for the shipment, if needed, used for filling in a CN22 or CN23 customs form (obsolete, ShipmentItems should be used)
      • IncotermInteger numberThe incoterm (DDU etc.) for international shipments.
    • DimensionssublistThe dimensions of the complete shipment.
      • HeightInteger numberHeight in cm.
      • LengthInteger numberLength in cm.
      • WeightInteger numberWeight in gramms
      • WidthInteger numberWidth in cm.
    • OptionListArray of objectsThe desired extra options. Note that any problem with options will result in a warning. In that case, the option is not stored, but the shipment is still accepted by the api. Only if you define multiple servicelevels or an impossible combination of options you will get an error and the shipment cannot be stored.
      • IdInteger numberrequiredMinimum value: 1The correct option id.
      • ValueStringMinimum length: 1The value for the option if there are no subitems for the option defined
      • OptionFieldsArray of objectsMinimum array items: 1Option value list if there are subitems defined. Note that if the extra values are map fields, then the ID is the exact id of those fields, not a numeric one!
        • IdInteger numberrequiredMinimum value: 1The correct option id
        • ValueStringMinimum length: 1Extra values for the parent option
    • PickupPointsublistInformation about the chosen pickup point (only use this if a servicelevel is selected that has a map point)
      • PointIdStringrequiredMinimum length: 3, maximum length: 25The id of the pickup point, see /pickuppoints/ endpoint
      • ExtendedInfoArray of objectsMinimum array items: 1Extended information for the pickup point, see /pickuppoints/
        • IdInteger numberrequiredMinimum value: 1The field id (has to be correct one)
        • ValueStringrequiredMinimum length: 1, maximum length: 100The field value entered
    • ShipmentItemsArray of objectsMinimum array items: 1Items list for the shipment. When used, it overrides the Customs information.
      • ArticleNumberStringMinimum length: 1The item EAN, SKU, UPC etc.
      • ColliInteger numberMinimum value: 1The colli the item is put in
      • CountInteger numberrequiredMinimum value: 1Number of items of this type
      • HSCodeInteger numberThe correct HS Code
      • IdStringrequiredMinimum length: 1Item id in the shop platform
      • NameStringrequiredMinimum length: 1, maximum length: 100Item name or description
      • OriginCountryCountryMinimum length: 2, maximum length: 3The country of origin of the item
      • TypeInteger numberMinimum value: 1, maximum value: 4Customs type, see list for possible values
      • ValueReal numberThe correct monetary value of the entire shipment content
      • DimensionssublistThe dimensions of a single item.
        • HeightInteger numberrequiredHeight in cm.
        • LengthInteger numberrequiredLength in cm.
        • WeightInteger numberWeight in gramms
        • WidthInteger numberrequiredWidth in cm.

JSON reply data

  • AppLinkurlAlways returnedA link for a one-time login on the correct system, pointing to the dayclosing page.
  • CallbackURLurlMinimum length: 1, maximum length: 100If a label was requested, then this will give the callback url for polling the labels endpoint. Only returned if there is no error during label creation.
  • ErrorsublistAlways returnedAny error will be reported here, see the error list for error codes and their meaning.
    • IdInteger numberAlways returnedMaximum value: 999The id of the error
    • InfoStringTextual error
  • ErrorListArray of objectsList of errors, to clarify the Error if possible
    • IdInteger numberAlways returnedMaximum value: 999The error id, see the error list
    • TekstStringAlways returnedMaximum length: 255Textual error for detailed information
  • ShipmentArray of objectsAlways returnedMinimum array items: 1, maximum array items: 50The result for each shipment in the request
    • ShopItemIdhex stringAlways returnedMaximum length: 60The id of the shipment/order in the platform as given in the request.
    • CarrierSelectsublistAlways returnedIdentification of the carrier that is used for this shipment
      • IdInteger numberAlways returnedMaximum value: 999A carrier id, see /carriers/ endpoint
      • NameStringAlways returnedMaximum length: 50The carrier name
    • ErrorListArray of objectsList of errors, to clarify the Error if possible
      • IdInteger numberAlways returnedMaximum value: 999The error id, see the error list
      • TekstStringAlways returnedMaximum length: 255Textual error for detailed information
    • WarningListArray of objectsWarnings, not critical and the shipment will be stored. If there are no warnings this list is absent
      • IdInteger numberAlways returnedMaximum value: 999The warning id, corresponds with error id list
      • TekstStringAlways returnedMaximum length: 255Textual error for detailed information

GET/shipments/newsince/:startNumber/:iso3339Date
POST/shipments/
POST/shipments/sendupdate/
POST/shipments/addstatusline/
PATCH/shipments/

Type numberDescription
1Gift
2Documents
3Sample
4Other