menu

Order: Address -> Parcel Locker

play_arrow
pause
play_arrow
stop

Creating a shipping order from specified address to parcel locker.

Here is the recomended approach to arrange a shipping order  from one address to parcel locker:

0 Get Rates You can optionally make a Get Rates request, typically you can make it during the checkout process in a shopping cart when the origin and destination of the parcel, as well as its weight and size, are already known.

  • You can specify "address-parcel_locker" as the delivery type to ensure that only carriers offering this specific type of delivery are returned in response. As you get the responce, you can offer the delivery options to your client with the name of the delivery option, price, and delivery time.
  • Additionally you can determine if a carrier supports address to Parcel Locker delivery by examining the Get Rates response. If the carrier has both "collection_target": "address" and "destination_target": "parcel_locker" listed, it indicates that the carrier can handle shipments from one address to a specified Parcel Locker.
  • When shipping to a parcel locker,  get the parcel_locker code which you will use in Place Order request after.
  • The Get Rates response includes a "nearest_parcel_locker_codes" container, which lists the nearest parcel lockers based on the provided postcode or coordinates.
  • If you provide precise longitude and latitude coordinates, the nearest_parcel_locker_codes  container will contain the closest parcel lockers, sorted from nearest to furthest.
  • If there are no parcel lockers found within 30km, the carrier will not be listed in the Get Rates response, indicating that the carrier cannot manage shipping to the specified location.

1 Place Order
 To place a shipping order to the parcel locker, you need to specify carrier code and parcel locker code, along with details like the sender's and receiver's addresses, parcel information, and other data mentioned in the example below.

Here is the full payload to order a shipment order from one address to another address:

POST https://api.sender.lv/api/sandbox/v1/orders
{
  • "carrier_code": "omniva-door-door", Specify the carrier code to order the service. This code can be obtained in the Get Rates request.
  • "from": { Container to specify the sender fields.
    • "firstname": "Inga", Sender's name as it appears in the passport, using only Latin characters.
    • "lastname": "Bārtule", Sender's last name as it appears in the passport, using only Latin characters.
    • "phone": "+37122654321", Sender's phone number with the country code, allowing only the '+' character and numbers.
    • "email": "[email protected]", Sender's email.
    • "country_iso": "LV", Sender's country in ISO format.
    • "city": "Rīga", Sender's city. Only Latin Extended-A characters allowed.
    • "postcode": "LV-1048", Sender's post code.
    • "address": "Slokas iela 28" Sender's address line 1 without city, postcode and country. Max 30 characters.
    } ,
  • "to": { Container to specify the destintation fields.
    • "parcel_locker_code": "9279", Only required for parcel locker shipments / if the parcel will be sent from a specified parcel locker. If parcel locker code is specified, address fields are served as backup/return address.
    • "firstname": "Mikhail", Receiver's name exactly as it is shown in the passport, using only Latin characters.
    • "lastname": "Tal", Receiver's surnam exactly as it is shown in the passport, using only Latin characters.
    • "phone": "+37122654321", Receiver's phone number with the country code, allowing only the '+' character and numbers.
    • "email": "[email protected]", Receiver's email.
    • "country_iso": "LV" Receivers's country in ISO format.
    } ,
  • "shipment_contents": "Dyson Airwrap 20mm Long Barrel Black Purple (970736-01)", Specify what's inside your package as precisely as possible.
  • "shipment_total_value": "31", Total cost of the items being shipped. Indicates carrier's maximum liability for a package that is lost or damaged.
  • "shipment_total_value_currency": "EUR", Currency for total cost of the items being shipped.
  • "package_type": "1", package type: 1 - Documents. 2 - Box/package. 3 - Pallet.
  • "packages": [ Packages container to specify each box or package individually.
    • { first package container
      • "weight": "0.250", Total weight of the package in KG
      • "width": "10", Total width of the package in CM
      • "height": "10", Total height of the package in CM
      • "depth": "5" Total depth of the package in CM
      }
    ] ,
  • "pickup_timestamp": "1744728512", Required only for pickup shipments, from specified address. We recommend obtaining valid pickup values for each carrier using the Get Rates request. This field not required for shipments from Parcel Locker.
  • "callback_urls": { Container for callback / hooks urls.
    • "success": "https://webhook.site/e3338662-625f-49e4-84ae-bba06d8d4b36", Our server will send a response to this callback URL once the order has been processed successfully.
    • "fail": "https://webhook.site/e3338662-625f-49e4-84ae-bba06d8d4b36" Our server will send a response to this callback URL if the order processing will be failed.
    }
}

  • The carrier code can be obtained in Get Rates request and can be stored in your system for future use.
  • Shipments to parcel lockers requires parcel locker code which can be obteined in Get Rates request or Get Parcel Lockers. We recomend to use Get Rates request to get parcel lockers, since it will return the closest parcel lockers based on destination post code or coordinates.
  • The receivers' address can be optionally provided even if you send to a parcel locker. The receivers address may serve as backup or return address option in case the parcel will be not picked up in the parcel locker.
  • When arranging a shipment from address to a parcel locker it is typically requires courier parcel pickup from the sender's address.
  • To arrange a courier's pickup the pickup time and date must be speciefied. When specifying a pickup time and date in the field pickup_timestamp, you should indicate a future date indicating when the parcel should be collected by the courier.
  • Since each carrier has its own policy regarding collection times, pinpointing the correct time period can be challenging. Therefore, it is recommended to parse the Get Rates response for possible collection options (collection->available_dates) and reuse these values in the Place Order request.
  • Once the order is placed, you will receive an order reference in the response, which can be used for future purposes such as checking the status of the order.


Callback Optionally, you can set up a callback to your server.

  • When our team processes the order you will get a POST to your callback URL from our server.
  • Some orders are processed almost instantly, while others may take longer (up to 20 minutes).
  • If an order cannot be processed for any reason, it will be canceled, and you will receive a callback response indicating that the order placement has failed. 
  • The Payload of the callback requst is the same as you get in response in Get Order request.
  • At present, our system will only send a callback request to your server a single time (whether the order was accepted on not). It will not send any further callbacks regarding updates to the order. If you require updates on your order status, you will need to manually make a Get Order Request. Details are provided below:

2 Get Order If you can't process callbacks or you just want to validate the status of your order,  you may need to manually make Get Order request  to ensure whether it was accepted or canceled, as well as to obtain a shipping label for your parcel.

  • Check for Shipping Labels. Be aware that certain carriers require shipping labels on parcels. You can confirm this through a Get Rates request by checking if a printer is necessary for the carrier. If a printer is required, you must acquire a shipping label in Get Order request and print it. If a printer is not needed, obtaining a shipping label is not necessary.
  • Check Order Status. If your order status is 'processed,' it means your order has been accepted, and you can expect the carrier to pick up your parcel. If the order is canceled it means the order can't be procssed for any reason. 
  • Update Shipping Status. You can periodically repeat the get order request to update your parcel's shipping status or other information on your side.


Please log in and add your sandbox to play this scenario in real-time